{

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 Description
merchant_key The key of the merchant.
order_key The key of the order

Parameters

Not applicable.

Request

Field Type M Description
method String M The payment method, e.g. IDEAL, PAYPAL, MASTERCARD.
_idealdetails Block C The payment details when the method is IDEAL.
+ issuer_id String M The id of the Issuer Bank. For issuer Ids check List payment methods of an Order
_carddetails Block C _The Card details for following Card Payments: MASTERCARD, VISA, BANCONTACT, VPAY, MAESTRO, AMEX. Either of plain card details or encrypted card details must be present.
+ _browserinformation Block M Information about what kind of response Browser accepts, User-Agent, and shopper IP.
++ shopper_ip String M IP of the device from which shopper is making payment.
++ accept String M Response types which browser accepts like text/html,application/xhtml+xml,application/xml.
++ user_agent String 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_carddetails Block O Card details with Card Holder Name, Card Number, Card Expiry date, Security code in plain text format.
++ card_holder_name String M Name of the Card Holder.
++ card_number String M Card Number.
++ card_expiry String M Card Expiry information including Month and Year.
+++ month String M The month when Card is going to be expired in the future.
+++ year String M The year when Card is going to be expired in the future.
++ security_code String 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_carddetails 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 M Card details in an encrypted format.

Notes:

  • There are no details for Payment Method PAYPAL.
  • Use encrypted Card details for increased security of the card details.

Response

Field Type M Description
id String M The payment identifier.
status String M The authorization status of the payment.
urls Block[] C _Required for authorization states REDIRECTED_FOR_AUTHENTICATION and REDIRECTED_FORAUTHORIZATION.
url Block M The redirect details for the shopper.
+ purpose String M The purpose of this URL.
+ method String M The HTTP method to be used, either "GET" or "POST".
+ url String M The url the shopper must be redirected to.
+ order Integer 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.

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"        : 2163180628,
        "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": "160701764",
          "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
         }
     ]
}'