{

Payments

Start the Payment for a given Order.

Start a Payment for a given Order

Starts a new payment for the given Order with payment details provided to the merchant by the Shopper.

POST /ps/api/public/v1/merchants/{merchant_key}/orders/{order_key}/payments

Identifiers

Name Type Description
merchant_key MerchantKey The key of the merchant.
order_key OrderKey The key of the order.

Parameters

Not applicable.

Request

Field Type M Description
method Enum(50) M The payment method, see below for the list of supported methods.
ideal_details Block C The payment details when the method is IDEAL.
+ issuer_id Enum(50) M The id of the Issuer Bank. For issuer Ids check List payment methods of an Order
card_details Block C The Card details for following Card Payments: MASTERCARD, VISA, BANCONTACT, V_PAY, MAESTRO, AMEX. Either of plain card details or encrypted card details must be present.
+ browser_information Block M Information about what kind of response Browser accepts, User-Agent, and shopper IP.
++ shopper_ip String(1, 45) M IP of the device from which shopper is making payment. This is an IPv4, IPv6, or an 'IPv4-mapped IPv6' address. The address should match the simple regular expression [0-9a-fA-F:.]{1,45}.
++ accept String(1, 255) M Response types which browser accepts like text/html,application/xhtml+xml,application/xml.
++ user_agent String(1, 255) M Browser and Operating System of a System from which Payment is being made. e.g. Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 Edge/18.18363
+ plain_card_details Block O Card details with Card Holder Name, Card Number, Card Expiry date, Security code in plain text format.
++ card_holder_name String(1, 35) M Name of the Card Holder.
++ card_number String(1, 19) M Card Number.
++ card_expiry Block M Card Expiry information including Month and Year.
+++ month String(2, 2) M The month when Card is going to be expired in the future.
+++ year String(2, 2) M The year when Card is going to be expired in the future.
++ security_code String(3, 4) O Security code on the card, usually CVV number. Security Code is optional for Maestro, V_Pay, and BanContact. It is mandatory for Mastercard, Visa, and Amex.
+ encrypted_card_details Block O Card details like Card Holder Name, Card Number, Card Expiry date, Security code in an encrypted format.Check Client Side Encryption Integration Manual for integrating client side encryption with your webshop.
++ data String (1, 4096) M Card details in an encrypted format.
elv_payment_input Block C The payment details when the method is ELV.
+ iban String(1, 35) M The IBAN of the shopper.

Supported payment methods:

Payment Method API Enum Value Notes
iDEAL IDEAL
PayPal PAYPAL No additional details needed.
MasterCard MASTERCARD See below.
Maestro MAESTRO See below.
American Express AMEX See below.
Visa VISA See below.
V-Pay V_PAY See below.
BanContact BANCONTACT See below.
Klarna Smoooth KLARNA No additional details needed.
Przeleway 24 PRZELEWY_24 No additional details needed.
BLIK BLIK No additional details needed.
ELV ELV

For credit card payments it is strongly recommended to use encrypted card details for increased security. The use of plain details is possible, but requires permissions from the compliance department.

Response

Field Type M Description
id PaymentIdentifier M The payment identifier.
status Enum(32) M The authorization status of the payment.
urls Block[] C Required for authorization states REDIRECTED_FOR_AUTHENTICATION and REDIRECTED_FOR_AUTHORIZATION.
url Block M The redirect details for the shopper.
+ purpose Enum(64) M The purpose of this URL.
+ method Enum(16) M The HTTP method to be used, either "GET" or "POST".
+ url Url M The url the shopper must be redirected to.
+ order Number(1,10) M Order in which urls should be displayed or handled.
+ parameters Map O Map with parameter name/values pairs for the body of the redirect request. The keys and values are of type String(1,255).

For the field purpose the following values are possible:

Purpose Description and required actions
REDIRECT Redirect the shopper to the specified URL using the given method and parameters.
HIDDEN_IFRAME The URL must be loaded in an i-frame that is hidden from the shopper. The size of the i-frame can be 0x0 or 1x1 pixels.
IFRAME The returned URL should not be loaded in an i-frame, but a POST request needs to be performed on it. The response of that request may need to be loaded inside an i-frame.

If the purpose is IFRAME, then (for now) 3DSv2 authentication needs to be performed. The URL points back to the payment system to start the authentication and response contains additional instructions that need to be carried out. For more information see also Credit/Debit Card Authentication.

For the field status the following values are possible:

Status Description
REDIRECTED_FOR_AUTHENTICATION The shopper needs to be redirected for authentication. The redirect details are specified in the URL section.
REDIRECTED_FOR_AUTHORIZATION The shopper needs to be redirected for authentication during the authorization phase. The redirect details are specified in the URL section.
CANCELED The payment is canceled, due to an error.
AUTHORIZED The payment is authorized.

HTTP Status

Status Meaning
201 (Created) The payment is created.
202 (Accepted) The payment is created and ended in canceled due to an error.
400 (Bad Request) The request was not valid.
400 (Bad Request) There was no web-direct route available.
403 (Forbidden) The merchant key is not correct.
404 (Not Found) The merchant reference for the subscription or the order key was not found.

iDeal payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/B72AD93F3CBFC47BB2173361D5DE573D/payments \
    -d '{
             "method" : "IDEAL",
             "ideal_details" : {
                       "issuer_id" : "ABNANL2A"
            }
        }'

< Http 201 Created 
<    '{
        "id"        : "pid2163180628t",
        "status"    : "REDIRECTED_FOR_AUTHORIZATION",
        "redirect"  : {
            "method"    : "GET",
            "url"       : "https://testsecure.docdatapayments.com/ps_sim/idealbanksimulator.jsf?trxid=1489155977162&amp;ec=2163180628&amp;returnUrl=%2Fps_sim%2Fparameters.jsf%3FcheckDigitId%3D2163180628B72AD93F3CBFC47BB2173361D5DE573D&amp;status=pay"
        }
     }'

PayPal payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/orders/3B88E0EF13E37D6A56AE949AD9E56961/payments \
    -d '{
            "method"  : "PAYPAL",
        }'

< Http 201 Created 
<    '{
          "id": "pid160701764t",
          "status": "REDIRECTED_FOR_AUTHENTICATION",
          "redirect": {
              "method": "GET",
              "url": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&useraction=commit&token=EC-9WB291683P236782S"
          }
      }'

Plain credit card payment example (3DSv1)

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/orders/3B88E0EF13E37D6A56AE949AD9E56961 \
    -d '{
        "method": "MASTERCARD",
        "card_details": {
        "browser_information" : {
            "shopper_ip" : "0.0.0.0",
            "accept" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
            "user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 Edge/18.18363"
        },
       "plain_card_details": {
         "card_holder_name":"John Doe",
         "card_number":"5555 555 5555 54444",
         "card_expiry": {
            "month":"01",
            "year":"23"
         },
         "security_code":"123"
      }
   }
}'

< Http 201 Created 
<   '{
    "id": "pid1607025630t",
    "status": "REDIRECTED_FOR_AUTHENTICATION",
    "urls": [
        {
            "purpose": "REDIRECT",
            "method": "POST",
            "url": "https://testsecure.docdatapayments.com/ps_sim/3dsecureauthentication.jsf?data=NTU1NTU1NTU1NTU1NDQ0NA==",
            "order": 1,
            "parameters": {
                "MD": "1607025630",
                "PaReq": "eJxVUdtOg0AQ/RXCs3aXpfSWYRssGvuANto+GwKbFi1Lu4C2Pvo9fpVf4gyFVknYzDl7cmbnDEwP+dZ6V6bMCu3bTo/bltJJkWZ67dur5d31yJ5KWG6MUuGzSmqjJESqLOO1srLUtxfBk9oLLjgf4jHmo/7AltCwElpfibY9AayDaGCSTawrCXGyv5k/SI6fQEULIVdmHkqHTD08uTcGduJAx7mim7Kq38oXvQXWMJAUta7MUXpiBKwDUJvtWdwjMRHALg9Y1FSVaHDIUjmfBevzH96KKEw+oteViD4DHxgpII0rJbuBLT6c8NGkPwDW8BDn1Fn+fH1brnvlchzpxMCOGgUn4Lp085cBTNZg8Ec5HtL7OwTqsCu0QgWmc64hVWUiH02qjOUIt+9he2KAXcaZ3VO6SUU5ooSybQA5ZhiNcLnTWBIARnLWro21C8bq3+J/Adr/tHg=",
                "TermUrl": "https://testsecure.docdatapayments.com/ps/returnFromAuthorization?paymentReference=1607025630D52DC2B7C9433E3CB96D6801F1FC1B07"
            }
        }
    ]
}'

Plain credit card payment example (3DSv2)

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/orders/3B88E0EF13E37D6A56AE949AD9E56961 \
    -d '{
        "method": "MASTERCARD",
        "card_details": {
        "browser_information" : {
            "shopper_ip" : "0.0.0.0",
            "accept" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
            "user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 Edge/18.18363"
        },
       "plain_card_details": {
         "card_holder_name":"John Doe",
         "card_number":"5555 555 5555 54444",
         "card_expiry": {
            "month":"01",
            "year":"23"
         },
         "security_code":"123"
      }
   }
}'

< Http 201 Created
<    '{
    "id": "pid1607034399t",
    "status": "REDIRECTED_FOR_AUTHENTICATION",
    "urls": [
        {
            "purpose": "HIDDEN_IFRAME",
            "method": "POST",
            "url": "https://testsecure.docdatapayments.com/ps_sim/nca_sim/finger_print",
            "order": 1,
            "parameters": {
                "threeDSMethodData": "eyd0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMJzonaHR0cHM6Ly9kdW1teS5jb20vbm90aWZpY2F0aW9uLXVybCcsJ3RocmVlRFNTZXJ2ZXJUcmFuc0lEJzonYzY3NjUzNjItNDQ5Ni00YjUwLTkyYzItYmRhYmNhZDQ3ZWVmIn0="
            }
        },
        {
            "purpose": "IFRAME",
            "method": "POST",
            "url": "https://testsecure.docdatapayments.com/ps/api/public/3dsv2/v1/transactions/c6765362-4496-4b50-92c2-bdabcad47eef/references/1607034399/authenticate",
            "order": 2
        }
    ]
}'

Encrypted credit card payment example (3DSv1)

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/orders/3B88E0EF13E37D6A56AE949AD9E56961 \
    -d '{
           "method": "MASTERCARD",
           "card_details": {
              "browser_information" : {
                    "shopper_ip" : "0.0.0.0",
                    "accept" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
                    "user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 Edge/18.18363"
               },
              "encrypted_card_details": {
                 "data" : "bjqdb57yTA9ianq6wYmz4qgf2JRdpwtdwyWOkz4YUQbKcOjJsXMCGS0K0G+q4EV5PJlL2m2FRLIyyFA3cZJBxDMncZ8p75BtMArQ+EgpkT39CVfOV49URxRHDaR1r4jUYCPqOXC32EJ8h95BjlTn8U421UvBcXt+c48QCLsZ5xf2b/z3UL7MIx1JTKUeKCKvczvIHip/q8zxv5gaKqJPzg19c4j0+8JbCk2f+Yw1sjJBQVdSd3q3at7BC7i4e1GuJK4ASAFFzK8u2qkZheNHe0JM2pZNx3KKb0YemyAPL7/6hZauyefV5xnRJKuxQFOh7aE98Pb/1NDWAK1EZFgcwg==|Y2xpZW50c2lkZS00"
             }
       }
 }'

< Http 201 Created 
<   '{
         "id": "pid1607034001t",
         "status": "REDIRECTED_FOR_AUTHENTICATION",
         "urls": [
             {
                 "purpose": "REDIRECT",
                 "method": "POST",
                 "url": "https://testsecure.docdatapayments.com/ps_sim/3dsecureauthentication.jsf?data=NTU1NTU1NTU1NTU1NDQ0NA==",
                 "order": 1,
                 "parameters": {
                     "MD": "1607034001",
                     "PaReq": "eJxVUe1ugkAQfBXC79bjOI1iljVWbOoPWtvaByDHBkn50AOq9mefp0/VJ+kdgraXkMzM7c2yszA75pn1QapKy8K3+cCxLSpkGadF4ttvm/vbiT1D2GwVUfBKslGEEFJVRQlZaezb6/kL7V3HdZyx6/HR0OOOjdCqCJ0vatuBC6yn2kDJbVTUCJHc360eUQgBrMOQk1oFODIH2JlAEeWES5W+A2shyLIpanVCzjmwnkCjMsxKGWXbsqqBGQrs2m3dGFTp58c0xtVinly+YOmGgTyEn8+HMFj6wEwFxFFN2E9ncTEdelPuAGt1iHLTF3++vi0hboTWOwV2ptH8TPRs+uavAjpGpVM+oTee6L/vGdBxVxakK3RYFwwxVRKfVEzK4q4Y6lBaBdh1nMWDiVLWOipTYrJsiXFMdTCucHhraQgwU866HbFumxr92/IvjEKwLg==",
                     "TermUrl": "https://testsecure.docdatapayments.com/ps/returnFromAuthorization?paymentReference=1607034001D433C3E239607C9E0CD38C7CE76D71C3"
                 }
             }
         ]
     }'

Encrypted credit card payment example(3DSv2)

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/orders/3B88E0EF13E37D6A56AE949AD9E56961 \
    -d '{
           "method": "MAESTRO",
           "card_details": {
              "browser_information" : {
                    "shopper_ip" : "0.0.0.0",
                    "accept" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
                    "user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 Edge/18.18363"
               },
              "encrypted_card_details": {
                 "data" : "AuPEzU8gUC3H/yXr7ZFnVK3KvdJYEfgbPLx/Ntb2LWOzrxElT5ueeijLVv9AKbKGpb1r9BcSdNB4CckxOm579L+ruCjK2gVKlKwaCPcHPy3bRHWOWBr+kcAAFwkHn1mCRIFmLXFtIBoukIT4pjdUygoQioEYZHymJu0FZGWIcHtZRevCTZr8tgLVYa3tM3ffqJ2wr2p+zDu++A4MVIN5IlhEp7zg75aZWWjmpIZj8M12Ne3EA4Sqzu01w3hxXpE6GbhSdnUQjR9Sde90ayGgaZtwbXy6Umy+boK2B7l4tRUvJAzqRoOG9F1GsH9gQs3O0DmtL/adClIr70Ue0ZCJNw==|Y2xpZW50c2lkZS00"
           }
       }
   }'

< Http 201 Created 
<   '{
         "id": "pid1607034038t",
         "status": "REDIRECTED_FOR_AUTHENTICATION",
         "urls": [
             {
                 "purpose": "HIDDEN_IFRAME",
                 "method": "POST",
                 "url": "https://testsecure.docdatapayments.com/ps_sim/nca_sim/finger_print",
                 "order": 1,
                 "parameters": {
                     "three_ds_method_data": "eyd0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMJzonaHR0cHM6Ly9kdW1teS5jb20vbm90aWZpY2F0aW9uLXVybCcsJ3RocmVlRFNTZXJ2ZXJUcmFuc0lEJzonYzA0YTZjMWEtZjZjYi00MWJmLWIyMTQtMTYwYjYwNDAzYWUwIn0="
                 }
             },
             {
                 "purpose": "IFRAME",
                 "method": "POST",
                 "url": "https://testsecure.docdatapayments.com/ps/public/3dsv2/transaction/c04a6c1a-f6cb-41bf-b214-160b60403ae0/1607034038",
                 "order": 2
         }
     ]
}'

ELV payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/B72AD93F3CBFC47BB2173361D5DE573D/payments \
    -d '{
             "method" : "ELV",
             "elv_payment_input" : {
                       "iban" : "DE36711500000009290701"
            }
        }'

< Http 201 Created 
<    '{
        "id"        : "pid2163180628t",
        "status"    : "AUTHORIZED",
     }'

Starts a Payment with a referenced Order

Starts a payment via a referenced authorized payment, which allows shopper authentication to be skipped under specific circumstances.

The referenced payment is used to perform a follow-up payment based on an existing authorized payment. This start request can only be used for very specific use-cases, such as a 'no-show' in the hospitality sector or for additional fuel charges ('delayed-charges') in the car-rental sector. These payments/orders are also called merchant initiated transactions.

The usage of this request requires approval from the compliance department.

The purpose of the referenced payment data is to skip the otherwise required strong shopper authentication (SCA). Only one exemption can be applied per referenced payment. It is not possible to perform a 'no-show'-payment and a 'delayed-charges'-payment with both pointing to the same original payment.

POST /ps/api/public/v1/merchants/{merchant_key}/orders/{order_key}/payments/referenced

Identifiers

Name Type Description
merchant_key MerchantKey The key of the merchant.
order_key OrderKey The key of the order.

Parameters

Not applicable.

Request

Field Type M Description
order_key OrderKey M The key of the original order.
sca_exemption Enum(32) M The requested SCA exemption type.

The allowed values for sca_exemption_type are:

Value Description
NO_SHOW A 'no-show', for example the shopper booked a room but did not show up.
DELAYED_CHARGES Additional charges, more fuel/kilometers used then pre-calculated or items from the minibar were consumed.

Response

Field Type M Description
id PaymentIdentifier M The payment identifier.
status Enum(32) M The authorization status of the payment.

HTTP Status

Status Meaning
201 (Created) The payment is created.
202 (Accepted) The payment is created and ended in canceled due to an error.
400 (Bad Request) The request was not valid.
400 (Bad Request) There was no web-direct route available.
403 (Forbidden) The merchant key is not correct.
404 (Not Found) The order key was not found.
> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/orders/3B88E0EF13E37D6A56AE949AD9E56961 \
    -d '{
        "order_key": "16965E9DA949EA65A6D73E31FE0E88B3",
        "sca_exemption": "NO_SHOW"
      }'

< Http 201 Created
<    '{
    "id": "pid1607025730t",
    "status": "AUTHORIZED"
}'