Authorise for Credit Card Payment

In order to authorise the Smart Transaction for credit card payment, you need to call POST Smart/Transactions/STX_xxx/prepare/creditcard:

Request
POST /api/v2/Smart/Transactions/STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2/prepare/creditcard HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
"container": {
"type": "credit_card",
"private": {
"owner": "Max Mustermann",
"pan": "411111XXXXXX1111",
"expiration_date": "2026-01-01T00:00:00+00:00",
"issuer": "VISA",
// ...
}
},
"callback_urls": {
"success_url": "https://www.example.org/3DS-success",
"failure_url": "https://www.example.org/3DS-failure"
}
}

This is the exact parameter mapping:

Returned from Frontend

Details for Credit Card Container

/encryptedData/masked/card_owner

private.owner

/encryptedData/masked/card_number

private.pan

/yearExp/value, /monthExp/value

private.expiration_date

/cardNumber/company

private.issuer

/encryptedData/crypted_container

private.transact_container

/encryptedData/crypted_skey

private.transact_skey_pubkey

/encryptedData/key_filename

private.transact_skey_keyname

/encryptedData/container_hash

private.transact_hash

The two callback URLs are needed to return the customer to your checkout after succeeded or failed 3-D Secure check. Whether a 3-D Secure check is needed, can be recognised by the API response.

If you have any questions about these details, please ask our friendly help desk.

In the best case, the Smart Transaction is authorised immediately:

Response (3-D Secure Not Required)
HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
// ...
"customer": {
"object": "payment.customers",
"id": "PCU_WZ3HENRNE2NSQMSQHRD58CPH7GHCA2",
"contact": {
"forename": "Mike",
"surname": "Mustermann",
"name": "Mike Mustermann",
"address": {
"street": "Musterstr.",
"street_number": "42",
"additional_address_data": "App. 97",
"postal_code": "09999",
"city": "Dorianburgh",
"country": "DE"
},
"email": "Eunice.Spencer89@example.net",
"mobile": "+491775555555",
"phone": "+495555555555",
"dob": "1965-12-31T00:00:00+01:00"
}
},
"container": {
"object": "payment.containers",
"id": "PCT_SF9XGHPVC2NSQX03V86EREAMMET7AZ"
},
// ... // ...
"transactions": [{
"object": "payment.transactions",
"id": "PCI_4YN04HZ4Z705GMRSJ5EW4J4X0ZDPNW"
}],
"created": "2020-10-29T14:13:41+01:00",
"updated": "2020-10-29T14:13:50+01:00",
"status": "approved",
// ...
"payment_method": "creditcard",
"trans_id": "30093721",
// ...
}

This means, no 3-D Secure check is needed.

Status approved means the payment is authorised and you should be able to capture it. Status failed means you must repeat the payment process. You must also repeat the payment process when you update the Smart Transaction. It is then set back to created.

If the option auto_capture is true, it would already capture the Smart Transaction. Status ok, received or collection means you can deliver. Status pending means you have to wait for one of these statusses. Status failed means the payment failed, and you must repeat the payment process.

In case a 3-D Secure check is needed, the status stays unchanged (created or with loyalty probably processing), and an iframe URL is added to the Smart Transaction:

Response (3-D Secure Required)
HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
// ...
"customer": {
"object": "payment.customers",
"id": "PCU_WZ3HENRNE2NSQMSQHRD58CPH7GHCA2",
"contact": {
"forename": "Mike",
"surname": "Mustermann",
"name": "Mike Mustermann",
"address": {
"street": "Musterstr.",
"street_number": "42",
"additional_address_data": "App. 97",
"postal_code": "09999",
"city": "Dorianburgh",
"country": "DE"
},
"email": "Eunice.Spencer89@example.net",
"mobile": "+491775555555",
"phone": "+495555555555",
"dob": "1965-12-31T00:00:00+01:00"
}
},
"container": {
"object": "payment.containers",
"id": "PCT_SF9XGHPVC2NSQX03V86EREAMMET7AZ"
},
"transactions": [{
"object": "payment.transactions",
"id": "PCI_4YN04HZ4Z705GMRSJ5EW4J4X0ZDPNW"
}],
"created": "2020-10-29T15:53:11+01:00",
"updated": "2020-10-29T15:53:25+01:00",
"status": "created",
// ...
"payment_method": "creditcard",
"trans_id": "30093750",
"iframe_url": "https://securepay.epayworldwide.com/securepay/pay.php?TID=93999999&IDENT=93999999_2910...",
// ...
}

In this case you have to offer the customer the iframe_url. He will then go through the 3-D Secure process.

After the 3-D Secure process the customer is either directed back to the success_url or failure_url you have passed when calling /prepare. When the success_url is called, the Smart Transaction can be expected to have status approved now. You can proceed to start the Smart Transaction and capture the payment. If auto_capture is set, the payment is already captured, and the Smart Transaction has either status ok, received or collection.

When the failure_url is called, you need to repeat the payment process.

You can ask our help desk to change the contract settings for demo transactions, so that you can test either with 3-D Secure or without.