Automation Test Endpoints

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.

Wait Endpoint

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:

  • Completing a 3DSv2 browser authentication flow (see als below);
  • Completing a 3DSv2 decoupled 3RI authentication flow;
  • Completing a Point-of-Sale payment.
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.

Authentication Completion

Card Payments

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.

3DS Version 1

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.

3DS Version 2

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.