Several test endpoints are available to complete certain steps in the payment flow to facilitate automated testing. These endpoints are only available in the test/sandbox environment and are not available in the production environment; therefore the endpoints have as starting point '/ps_sim/' instead of '/ps/'.
Finally, these endpoints can only be used after an API request start payment
is performed. There are no automation
endpoints for completing shopper actions inside the CM.com payment menu.
A wait endpoint is available to wait for the payment transition into a final state, for example AUTHORIZED
or
CANCELED
, and that the order status change notification (Introduction) is executed. This request
waits up to 20 seconds before returning a response.
This endpoint should be used for the following:
GET /ps_sim/wait-for/payments/{payment_id}
Identifiers
Name | Type | Description |
---|---|---|
payment_id | PaymentIdentifier | The payment identifier, as received in the start payment response. |
Parameters
Not applicable.
Request
Not applicable.
Response No content is returned.
HTTP Status
Status | Meaning |
---|---|
204 (No Content) | The payment is in final authorization state. |
404 (Not Found) | The payment was not found. |
408 (Request Timeout) | If the payment took too long to complete. |
For card payments the 3DS authentication step needs to be completed. A different endpoint needs to be used, depending on the used 3DS version. For simplicity, if the start response for a card payments contains a redirect instruction (see also Start Payment), then it can be assumed that 3DS version 1 is used for authentication. Otherwise, it is 3DS version 2.
For 3DS version 1, a PaRes is needed to complete the authentication part of the payment flow. The PaRes can be obtained via the following post operation.
POST /ps_sim/3ds/v1/pares-generator/{payment_id}
Identifiers
Name | Type | Description |
---|---|---|
payment_id | PaymentIdentifier | The payment identifier, as received in the start payment response in the POST-parameters map under the key 'MD'. |
Parameters
Not applicable.
Request
Field | Type | M | Description |
---|---|---|---|
status | String(1) | O | The authentication status ('Y' for successful authentication; 'N' for failed or aborted authentication). The default is 'Y'. |
pareq | String | M | The PaReq data, as received in the start payment response in the POST-parameters map under the key 'PaReq'. |
Response
The response is the generated PaRes and is returned using content-type text/plain
. The PaRes is then send to PS
via the TermUrl
, as received in the start payment response in the POST-parameters map under the key TermUrl
. The send
operation is a form-POST with content type application/x-www-form-urlencoded
and parameter PaRes
containing the
received Pares value.
For example, if the start response of card payment is the following:
{
"result": "CHALLENGE",
"urls": [
{
"purpose": "REDIRECT",
"url": "https://acceptsecure.docdatapayments.com/ps_sim/3dsecureauthentication.jsf?data=NTU1NTU1NTU1NTU1NDU1MA==",
"method": "POST",
"order": 1,
"parameters": {
"MD": "2164143269",
"TermUrl": "https://acceptsecure.docdatapayments.com/ps/returnFromAuthorization?paymentReference=2164143269B14E8B30C5CED1811D1A98F3958289A7",
"PaReq": "<some long encoded value>"
}
}
]
}
Then the curl command to generate the PaRes is:
curl -d '{ "status" : "Y", "pareq" : "<some long encoded value>"}' -H 'application/json' -X POST https://testsecure.docdatapayments.com/ps_sim/3ds/v1/pares-generator/2164143269
And the curl command to complete the payment is:
curl -d 'PaRes=<received value from /ps_sim/3ds/v1/pares-generator/...>' -X POST https://testsecure.docdatapayments.com/ps/returnFromAuthorization?paymentReference=2164143269B14E8B30C5CED1811D1A98F3958289A7
The last command should result in a redirect to the landing page for the shopper.
HTTP Status
Status | Meaning |
---|---|
200 (Ok) | The PaRes is generated. |
400 (Bad Request) | The payment identifier is incorrect. |
404 (Not Found) | The specified payment is not found. |
For 3DS version 2, PS needs to be notified (simulated notification) that the shopper completed the authentication and that the authorization request can be performed. The same endpoint can be used to complete browser authentication and decoupled 3RI authentication.
The pending authentication request is completed by sending the following POST-request:
POST /ps_sim/3ds/v2/complete-authentication/{payment_id}
Identifiers
Name | Type | Description |
---|---|---|
payment_id | PaymentIdentifier | The payment identifier, as received in the start payment response. |
If the following start payment response is received:
{
"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
}
]
}
Then the following curl
command completes the authentication flow:
curl -d '{ "status" : "Y" }' -H 'application/json' -X POST https://testsecure.docdatapayments.com/ps_sim/3ds/v2/complete-authentication/pid1607034399t
Parameters
Not applicable.
Request
Field | Type | M | Description |
---|---|---|---|
status | String(1) | O | The authentication status ('Y' for successful authentication; 'N' for failed or aborted authentication). The default is 'Y' |
Response No content is returned.
HTTP Status
Status | Meaning |
---|---|
204 (No Content) | The authentication is processed. |
404 (Not Found) | The 3DS transaction is not found. |