Start the Payment for a given Order.

Start Payment

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

NameTypeDescription
merchant_keyMerchantKeyThe key of the merchant.
order_keyOrderKeyThe key of the order.

Parameters

Not applicable.

Request

FieldTypeMDescription
methodPaymentMethodMThe payment method, see below for the list of supported methods. See also the payment method types.
authentication_methodsAuthenticationMethod[]CThe used authentication methods that successfully authenticated the shopper at the webshop. Required for BanContact WIP, otherwise optional. See also the authentication method types.
ideal_detailsBlockODeprecated : The payment details when the method is IDEAL.
+ issuer_idEnum(50)ODeprecated : The id of the Issuer Bank. For issuer Ids check List payment methods of an Order
card_detailsBlockCThe 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_informationBlockMInformation about what kind of response Browser accepts, User-Agent, and shopper IP.
++ shopper_ipString(1, 45)MIP 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}.
++ acceptString(1, 255)MResponse types which browser accepts like text/html,application/xhtml+xml,application/xml.
++ user_agentString(1, 255)MBrowser 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_detailsBlockOCard details with Card Holder Name, Card Number, Card Expiry date, Security code in plain text format.
++ card_holder_nameString(1, 35)MName of the Card Holder.
++ card_numberString(1, 19)MCard Number.
++ card_expiryBlockMCard Expiry information including Month and Year.
+++ monthString(2, 2)MThe month when Card is going to be expired in the future.
+++ yearString(2, 2)MThe year when Card is going to be expired in the future.
++ security_codeString(3, 4)CSecurity code (CVV/CID/CVC2) on the card. See below when the code is required.
+ encrypted_card_detailsBlockOCard details like Card Holder Name, Card Number, Card Expiry date, Security code in an encrypted format.Check Client Side Encryption for integrating client side encryption with your webshop.
++ dataString (1, 4096)MCard details in an encrypted format.
+ three_ri_authenticationBlockOThe 3RI authentication details.
elv_payment_detailsBlockCThe payment details when the method is ELV.
+ ibanString(1, 35)MThe IBAN of the shopper.
giro_payment_detailsBlockCThe payment details when the method is Giro pay.
+ account_numberString(1, 35)MThe account number of the shopper.
+ bank_codelongMThe bank code of the shopper.
bank_transfer_detailsBlockCThe payment details when the method is Bank Transfer.
+ email_addressString(1, 200)MThe email address of shopper to send bank details.
sepa_direct_debit_detailsBlockCThe payment details when the method is Sepa Direct Debit.
+ mandate_numberString(1, 35)CThe mandate number. Mandatory when IBAN is not provided.
+ ibanString(5, 34)CThe IBAN of the shopper. Mandatory when mandate number is not provided.
+ bicString(8, 11)OThe BIC of the shopper bank account. Can only be provided along with IBAN and not with mandate number.
point_of_sale_detailsBlockCThe payment details when the method is POINT_OF_SALE
+ terminal_idString(1, 35)MThe terminal_id of the merchant.
inthree_detailsBlockCThe payment details when the method is IN3.
+ shopper_ipString(1, 45)MIP 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}.

Note: Either browser_information or three_ri_authentication must be present in the card details.

Details about the 3RI authentication block and process can be found on 3RI Authentication.

The security code is :

  • required when using Amex, MasterCard, or Visa as payment method;
  • optional when using Maestro, VPay, or BanContact as payment method;
  • not required when submitting the credit card payment as moto-payment;
  • not required when submitting the credit card payment with 3RI authentication.

Supported payment methods:

Payment MethodAPI Enum ValueNotes
iDEALIDEAL
PayPalPAYPALNo additional details needed.
MasterCardMASTERCARDSee below.
MaestroMAESTROSee below.
American ExpressAMEXSee below.
VisaVISASee below.
V-PayV_PAYSee below.
BanContact (WIP)BANCONTACTSee below.
IN3IN_THREE
Klarna SmooothKLARNANo additional details needed.
Przeleway 24PRZELEWY_24No additional details needed.
BLIKBLIKNo additional details needed.
ELVELV
Sofort UeberweisungSOFORT_UEBERWEISUNGNo additional details needed.
EbankingEBANKINGNo additional details needed.
GiroPayGIROPAY
Bank TransferBANK_TRANSFER
Sepa Direct DebitSEPA_DIRECT_DEBIT
Point of Sale (POS)POINT_OF_SALE
KBCKBCNo additional details needed.
CBCCBCNo additional details needed.

Notes:

  • For credit and debit card payments (MasterCard, Maestro, American Express, Visa, V-Pay, BanContact) it is strongly recommended to use encrypted card details for increased security. The use of plain details is possible, but requires permission from the compliance department.
  • For BanContact WIP, and not regular BanContact, the field authentication_methods is required and cannot contain the value NOT_AUTHENTICATED.

Response

FieldTypeMDescription
idPaymentIdentifierMThe payment identifier.
statusEnum(32)MThe authorization status of the payment.
urlsBlock[]CRequired for authorization states REDIRECTED_FOR_AUTHENTICATION and REDIRECTED_FOR_AUTHORIZATION.
urlBlockMThe redirect details for the shopper.
+ purposeEnum(64)MThe purpose of this URL.
+ methodEnum(16)MThe HTTP method to be used, either "GET" or "POST".
+ urlUrlMThe url the shopper must be redirected to.
+ orderNumber(1, 10)MOrder in which urls should be displayed or handled.
+ parametersMapOMap with parameter name/values pairs for the body of the redirect request. The keys and values are of type String(1,255).
bank_transfer_detailsBlockCBank transfer details for the shopper.
+ beneficiary_nameString(1, 35)MBeneficiary name.
+ beneficiary_cityString(1, 35)MBeneficiary city.
+ beneficiary_countryString(1, 35)MBeneficiary country.
+ bank_nameString(1, 105)MBank name.
+ bank_cityString(1, 35)MBank city.
+ bicString(1, 12)OBIC.
+ ibanString(1, 128)OIBAN formatted.
+ address_line1String(1, 35)OFirst address line with address of beneficiary bank.
+ address_line2String(1, 35)OSecond address line with address of beneficiary bank.
+ address_line3String(1, 35)OThird address line with address of beneficiary bank.
+ address_line4String(1, 35)OFourth address line with address of beneficiary bank.
point_of_sale_detailsBlockCPoint Of Sale details for the merchant.
+ wakeupBlockMWake-up address details to wakeup terminal for contactless payments.
++ ipString(1, 255)MWake-up ip address of terminal in local network.
++ portNumber(0, 65535)MWake-up port.

For the field purpose the following values are possible:

PurposeDescription and required actions
REDIRECTRedirect the shopper to the specified URL using the given method and parameters.
HIDDEN_IFRAMEThe 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.
IFRAMEThe 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:

StatusDescription
REDIRECTED_FOR_AUTHENTICATIONThe shopper needs to be redirected for authentication. The redirect details are specified in the URL section.
REDIRECTED_FOR_AUTHORIZATIONThe shopper needs to be redirected for authentication during the authorization phase. The redirect details are specified in the URL section.
CANCELEDThe payment is canceled, due to an error.
AUTHENTICATION_REQUESTEDThe shopper needs to complete the authentication request that is pushed to its device.
AUTHORIZEDThe payment is authorized.
AUTHORIZATION_REQUESTEDThe authorization has been requested for the payment.

HTTP Status

StatusMeaning
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://secure.sandbox.pay.cm.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/B72AD93F3CBFC47BB2173361D5DE573D/payments \
    -d '{
             "method" : "IDEAL"             
        }'
 
< Http 201 Created 
<    '{
        "id"        : "pid2163180628t",
        "status"    : "REDIRECTED_FOR_AUTHORIZATION",
        "urls"  : {
            "purpose": "REDIRECT",
            "method"    : "GET",
            "url"       : "https://secure.sandbox.pay.cm.com/ps_sim/idealbanksimulator.jsf?trxid=1489155977162&amp;ec=2163180628&amp;returnUrl=%2Fps_sim%2Fparameters.jsf%3FcheckDigitId%3D2163180628B72AD93F3CBFC47BB2173361D5DE573D&amp;status=pay",
            "order": 1
        }
     }'

PayPal payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/orders/3B88E0EF13E37D6A56AE949AD9E56961/payments \
    -d '{
            "method"  : "PAYPAL",
        }'
 
< Http 201 Created 
<    '{
          "id": "pid160701764t",
          "status": "REDIRECTED_FOR_AUTHENTICATION",
          "urls": {
              "purpose": "REDIRECT",
              "method": "GET",
              "url": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&useraction=commit&token=EC-9WB291683P236782S",
              "order": 1
          }
      }'

Plain credit card payment example (3DSv1)

> curl \
	-X POST \
	--header 'Content-Type: application/json' \
	--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
	https://secure.sandbox.pay.cm.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://secure.sandbox.pay.cm.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://secure.sandbox.pay.cm.com/ps/returnFromAuthorization?paymentReference=1607025630D52DC2B7C9433E3CB96D6801F1FC1B07"
            }
        }
    ]
}'

Plain credit card payment example (3DSv2)

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.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://secure.sandbox.pay.cm.com/ps_sim/nca_sim/finger_print",
            "order": 1,
            "parameters": {
                "threeDSMethodData": "eyd0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMJzonaHR0cHM6Ly9kdW1teS5jb20vbm90aWZpY2F0aW9uLXVybCcsJ3RocmVlRFNTZXJ2ZXJUcmFuc0lEJzonYzY3NjUzNjItNDQ5Ni00YjUwLTkyYzItYmRhYmNhZDQ3ZWVmIn0="
            }
        },
        {
            "purpose": "IFRAME",
            "method": "POST",
            "url": "https://secure.sandbox.pay.cm.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://secure.sandbox.pay.cm.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://secure.sandbox.pay.cm.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://secure.sandbox.pay.cm.com/ps/returnFromAuthorization?paymentReference=1607034001D433C3E239607C9E0CD38C7CE76D71C3"
                 }
             }
         ]
     }'

Encrypted credit card payment example(3DSv2)

> curl \
	-X POST \
	--header 'Content-Type: application/json' \
	--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
	https://secure.sandbox.pay.cm.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://secure.sandbox.pay.cm.com/ps_sim/nca_sim/finger_print",
                 "order": 1,
                 "parameters": {
                     "three_ds_method_data": "eyd0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMJzonaHR0cHM6Ly9kdW1teS5jb20vbm90aWZpY2F0aW9uLXVybCcsJ3RocmVlRFNTZXJ2ZXJUcmFuc0lEJzonYzA0YTZjMWEtZjZjYi00MWJmLWIyMTQtMTYwYjYwNDAzYWUwIn0="
                 }
             },
             {
                 "purpose": "IFRAME",
                 "method": "POST",
                 "url": "https://secure.sandbox.pay.cm.com/ps/public/3dsv2/transaction/c04a6c1a-f6cb-41bf-b214-160b60403ae0/1607034038",
                 "order": 2
         }
     ]
}'

Klarna Smooth payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/orders/7E0D6CE5759AC785FC600C8C00AE0650/payments \
    -d '{
            "method"  : "KLARNA"
        }'
 
< Http 201 Created 
<    '{
           "id": "pid4911970290t",
           "status": "REDIRECTED_FOR_AUTHENTICATION",
           "urls": [
               {
                   "purpose": "REDIRECT",
                   "method": "GET",
                   "url": "https://pay.playground.klarna.com/eu/hpp/payments/1ZTCX1Q",
                   "order": 1
               }
           ]
       }'

Przelewy24 payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/orders/FC7B384453B0A73B85F6FA079E95EF1B/payments \
    -d '{
            "method"  : "PRZELEWY_24"
        }'
 
< Http 201 Created 
<    '{
           "id": "pid4911970328t",
           "status": "REDIRECTED_FOR_AUTHORIZATION",
           "urls": [
               {
                   "purpose": "REDIRECT",
                   "method": "GET",
                   "url": "https://secure.sandbox.pay.cm.com/ps_sim/przelewy24/pay/trnRequest/619d5f28-7e0f-4465-9be1-28b31528063d",
                   "order": 1
               }
           ]
       }'

Blik payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/orders/7B5AF2B4C4137C095C6045F0996EF4FE/payments \
    -d '{
            "method"  : "BLIK"
        }'
 
< Http 201 Created 
<    '{
           "id": "pid4911970344t",
           "status": "REDIRECTED_FOR_AUTHORIZATION",
           "urls": [
               {
                   "purpose": "REDIRECT",
                   "method": "GET",
                   "url": "https://secure.sandbox.pay.cm.com/ps_sim/przelewy24/pay/trnRequest/8ee1d5f6-8b1c-4528-99f7-8a98a8e09fbb",
                   "order": 1
               }
           ]
       }'

ELV payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/B72AD93F3CBFC47BB2173361D5DE573D/payments \
    -d '{
             "method" : "ELV",
             "elv_payment_details" : {
                       "iban" : "DE64603900000272082007"
            }
        }'
 
< Http 201 Created 
<    '{
        "id"        : "pid2163180628t",
        "status"    : "AUTHORIZED",
     }'

Sofort Ueberweisung payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic dGVzdHNob3A6d2RzWUZGUUw=' \
    https://secure.sandbox.pay.cm.com/ps/api/public/v1/merchants/275e8be1-3b66-47ed-a6e9-bdb2c7c7d831/orders/F40CAD727061DB859DE93E93ADCD9079/payments' \
    -d '{
            "method": "SOFORT_UEBERWEISUNG"
        }'

< Http 201 Created
<    '{
           "id": "pid1607119702t",
           "status": "REDIRECTED_FOR_AUTHORIZATION",
           "urls": [
               {
                   "purpose": "REDIRECT",
                   "method": "POST",
                   "url": "https://secure.sandbox.pay.cm.com/ps_sim/SofortSimulator?user_id=34196&project_id=252647&amount=33.3&currency_id=EUR&reason_1=PID1607119702T+ddp+testshop&reason_2=Order+12345&user_variable_0=1607119702&user_variable_1=159895246&user_variable_2=http%3A%2F%2Fsecure.sandbox.pay.cm.com%2Fps%2FreturnFromAuthorization%3FpaymentReference%3D1607119702F40CAD727061DB859DE93E93ADCD9079&user_variable_3=http%3A%2F%2Fsecure.sandbox.pay.cm.com%2Fps%2FreturnFromShopperCancelled%3FpaymentReference%3D1607119702F40CAD727061DB859DE93E93ADCD9079&language_id=NL&sender_country_id=DE&hash=c9f075ec78b32101db5f9a2fd4c01a93486d73689cbc2c2a0f7cd23bbe172a65",
                   "order": 1
               }
           ]
       }'

IN3 payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/orders/63D742045C3580B50D35CF96691C6E0C/payments \
    -d '{
            "method"  : "IN_THREE", 
            "inthree_details" : {
                "shopper_ip" : "0.0.0.0"
            }
        }'
 
< Http 201 Created 
<    '{
           "id": "pid4914460071t",
           "status": "REDIRECTED_FOR_AUTHORIZATION",
           "urls": [
               {
                   "purpose": "REDIRECT",
                   "method": "GET",
                   "url": "https://test.docdatapayments.com/ps_sim/capayable/pay/46975c10-6ee5-4236-849d-5fd5b367fa59?returnUrl=https%3A%2F%2Fsecure.sandbox.pay.cm.com%2Fps%2FreturnFromAuthorization%3FpaymentReference%3D491446007163D742045C3580B50D35CF96691C6E0C&shopOrderExchangeUrl=https%3A%2F%2Fsecure.sandbox.pay.cm.com%2Fps%2FreturnFromShopperAbandoned%3FpaymentReference%3D491446007163D742045C3580B50D35CF96691C6E0C",
                   "order": 1
               }
           ]
       }'

Sofort Ebanking payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic dGVzdHNob3A6d2RzWUZGUUw=' \
    https://secure.sandbox.pay.cm.com/ps/api/public/v1/merchants/275e8be1-3b66-47ed-a6e9-bdb2c7c7d831/orders/B52B5826436F6CDC91A65E2BD78C5E7A/payments' \
    -d '{
            "method": "EBANKING"
        }'

< Http 201 Created
<    '{
           "id": "pid1607119725t",
           "status": "REDIRECTED_FOR_AUTHORIZATION",
           "urls": [
               {
                   "purpose": "REDIRECT",
                   "method": "POST",
                   "url": "https://secure.sandbox.pay.cm.com/ps_sim/SofortSimulator?user_id=24105&project_id=203856&amount=33.3&currency_id=EUR&reason_1=PID1607119725T+ddp+testshop&reason_2=Order+12345&user_variable_0=1607119725&user_variable_1=159895251&user_variable_2=http%3A%2F%2Fsecure.sandbox.pay.cm.com%2Fps%2FreturnFromAuthorization%3FpaymentReference%3D1607119725B52B5826436F6CDC91A65E2BD78C5E7A&user_variable_3=http%3A%2F%2Fsecure.sandbox.pay.cm.com%2Fps%2FreturnFromShopperCancelled%3FpaymentReference%3D1607119725B52B5826436F6CDC91A65E2BD78C5E7A&language_id=NL&sender_country_id=DE&hash=1cb747c4e9684adcf7bd87fc778cc720786d7d6887ff6e8f9977abf71f438e28",
                   "order": 1
               }
           ]
       }'

GIROPAY payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/B72AD93F3CBFC47BB2173361D5DE573D/payments \
    -d '{
             "method" : "GIROPAY",
             "giro_payment_details" : {
                       "account_number": "123456",
                       "bank_code": 44448888
            }
        }'
 
< Http 201 Created 
<    '{
           "id": "pid2163180628t",
           "status": "REDIRECTED_FOR_AUTHORIZATION",
           "urls": [
               {
                   "purpose": "REDIRECT",
                   "method": "GET",
                   "url": "http://localhost:9090/ps_sim/giropaybanksimulator.jsf?amount=33.30&currency=EUR&ref=1607121000&branch=+&clientName=41962&salesChannel=41962_doc_eur&returnUrlPaid=http%3A%2F%2Flocalhost%3A8080%2Fps%2FreturnFromAuthorization%3FpaymentReference%3D160712100002CE9BEE3D7F36522181A181CAFAB570&returnUrlError=http%3A%2F%2Flocalhost%3A8080%2Fps%2FreturnFromAuthorization%3FpaymentReference%3D160712100002CE9BEE3D7F36522181A181CAFAB570&returnUrlCanceled=http%3A%2F%2Flocalhost%3A8080%2Fps%2FreturnFromAuthorization%3FpaymentReference%3D160712100002CE9BEE3D7F36522181A181CAFAB570",
                   "order": 1
               }
           ]
       }'

Bank Transfer payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/B72AD93F3CBFC47BB2173361D5DE573D/payments \
    -d '{
             "method" : "BANK_TRANSFER",
             "bank_transfer_details" : {
                                 "email_address" : "[email protected]"
                               }
        }'
 
< Http 201 Created 
<    '{
          "id": "pid1607123245t",
          "status": "AUTHORIZED",
          "bank_transfer_details": {
              "beneficiary_name": "CM.com stichting",
              "beneficiary_city": "Utrecht",
              "beneficiary_country": "NL",
              "bank_name": "DEUTSCHE BANK A.G. AMSTERDAM ",
              "bank_city": "AMSTERDAM",
              "bic": "DEUTNL2A",
              "iban": "NL45DEUT0556977556",
              "address_line1": "POB 2065",
              "address_line2": "8022 ZURICH"
          }
      }'

Sepa Direct Debit payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/3B88E0EF13E37D6A56AE949AD9E56961/payments \
    -d '{
        "method"                    : "SEPA_DIRECT_DEBIT",
        "sepa_direct_debit_details" : {
                             "iban"     : "NL47INGB0007673523",
                             "bic"  : "RABONL2A",
                             "mandate"  : "mandateNumber"
        }
    }'
 
< Http 201 Created
<    '{
        "id"        : 2163179782,
        "status"    : "AUTHORIZED"
    }'

Point of sale payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/B72131B00298FA10A4396CD416DBC7EA/payments \
    -d '{
        "method"                    : "POINT_OF_SALE",
        "point_of_sale_details" : {
                             "terminal_id"     : "E_DDT1"
        }
    }'
 
< Http 201 Created
<    '{
        "id"        : pid1607193683t,
        "status"    : "AUTHORIZATION_REQUESTED",
        "point_of_sale_details": {
            "wakeup": {
                "ip": "127.0.0.1",
                "port": 8080
            }
        }
    }'

KBC payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/orders/7B5AF2B4C4137C095C6045F0996EF4FE/payments \
    -d '{
            "method"  : "KBC"
        }'
 
< Http 201 Created 
<    '{
   		 "id": "pid4911970344t",
   		 "status": "REDIRECTED_FOR_AUTHORIZATION",
   		 "urls": [
        	{
           		 "purpose": "REDIRECT",
           		 "method": "GET",
            	 "url": "https://testsecure.docdatapayments.com/ps_sim/kbcacquirersimulator.jsf?langWebSite=N&amp;olpId=TODO&amp;olpCtx=vikIRmWLMoWtBnVEEb5x4r1KxbWTV%2BoV1mqnC9DeCkp6KJNFUdl639IIqnm7k9f5OHFXtl9OjIE6wgbvBICq04CKBZC8t%2F7bcV7atZyKXzWSGsDtbkGHxVNm5nuKOPyfl4eW8tnIFwG87R7fQaw0LSBmaGqVdtSiJfHaqyDPFZ4iNhSqM7bsbdWWJOpWC4VgEsxnwEF4Mym%2F0iDLbBx%2BzLaeDI43aTi47dr7DhsxKn%2BZKOR9IEdNrMUbVn%2F95Bssp6dmCpWT3w90gusH6VMq7VtJE3sxQGJZPTh6x7B1u%2BGz0shV1tHgYdiuHYa5dkIVeXsa819i9tjewjqs4cGSmWgpt%2B54ECGWty%2FyzOqjdkc4cXK3iIdlatxukxH1jEgPTw%2FzDREeyn3us9Xbr%2F0hHto%3D&amp;olpVer=3.0&amp;olpCompany=KBC",
            	 "order": 1
        	}
    	]
	}'

CBC payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/orders/7B5AF2B4C4137C095C6045F0996EF4FE/payments \
    -d '{
            "method"  : "CBC"
        }'
 
< Http 201 Created 
<    '{
   		 "id": "pid4911970344t",
   		 "status": "REDIRECTED_FOR_AUTHORIZATION",
   		 "urls": [
        	{
           		 "purpose": "REDIRECT",
           		 "method": "GET",
            	 "url": "https://testsecure.docdatapayments.com/ps_sim/kbcacquirersimulator.jsf?langWebSite=N&amp;olpId=TODO&amp;olpCtx=vikIRmWLMoWtBnVEEb5x4r1KxbWTV%2BoV1mqnC9DeCkp6KJNFUdl639IIqnm7k9f5OHFXtl9OjIE6wgbvBICq04CKBZC8t%2F7bcV7atZyKXzWSGsDtbkGHxVNm5nuKOPyfl4eW8tnIFwG87R7fQaw0LSBmaGqVdtSiJfHaqyDPFZ4iNhSqM7bsbdWWJOpWC4VgEsxnwEF4Mym%2F0iDLbBx%2BzLaeDI43aTi47dr7DhsxKn%2BZKOR9IEdNrMUbVn%2F95Bssp6dmCpWT3w90gusH6VMq7VtJE3sxQGJZPTh6x7B1u%2BGz0shV1tHgYdiuHYa5dkIVeXsa819i9tjewjqs4cGSmWgpt%2B54ECGWty%2FyzOqjdkc4cXK3iIdlatxukxH1jEgPTw%2FzDREeyn3us9Xbr%2F0hHto%3D&amp;olpVer=3.0&amp;olpCompany=CBC",
            	 "order": 1
        	}
    	]
	}'

Start Payment with 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

NameTypeDescription
merchant_keyMerchantKeyThe key of the merchant.
order_keyOrderKeyThe key of the order.

Parameters

Not applicable.

Request

FieldTypeMDescription
order_keyOrderKeyMThe key of the original order.
sca_exemptionEnum(32)MThe requested SCA exemption type.
three_ri_authenticationBlockOThe 3RI authentication details.

Details about the 3RI authentication block and process can be found on 3RI Authentication.

The allowed values for sca_exemption are:

ValueDescription
NO_SHOWA 'no-show', for example the shopper booked a room but did not show up.
DELAYED_CHARGESAdditional charges, more fuel/kilometers used then pre-calculated or items from the minibar were consumed.

Response

FieldTypeMDescription
idPaymentIdentifierMThe payment identifier.
statusEnum(32)MThe authorization status of the payment.

HTTP Status

StatusMeaning
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://secure.sandbox.pay.cm.com/ps/api/public/orders/3B88E0EF13E37D6A56AE949AD9E56961 \
    -d '{
        "order_key": "16965E9DA949EA65A6D73E31FE0E88B3",
        "sca_exemption": "NO_SHOW"
      }'
 
< Http 201 Created
<    '{
    "id": "pid1607025730t",
    "status": "AUTHORIZED"
}'