Start the 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}/paymentsIdentifiers
| 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:
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&ec=2163180628&returnUrl=%2Fps_sim%2Fparameters.jsf%3FcheckDigitId%3D2163180628B72AD93F3CBFC47BB2173361D5DE573D&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
}
]
}'