Authorise for PayPal Payment

First we need to authorise the PayPal payment. The procedure is much like credit card payment. We start with an API call to the endpoint for PayPal authorisation:

Request
POST /api/v2/Smart/Transactions/STX_xxx/prepare/paypal HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
{
"callback_urls": {
"success_url": "https://shop.example.com/auth-success",
"failure_url": "https://shop.example.com/auth-failure"
}
}

This are the parameters:

Parameter

Explanation

success_url

Your URL to direct the customer to after successful authorization or conclusion.

failure_url

Your URL to direct the customer when the authorization failed, or he canceled the process.

If everything is fine, the API responds with 200 OK and the object representation. The status is still created (or processing) and there is an iframe_url:

Response
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"object": "smart.transactions",
"id": "STX_HNYFD9RMK2NTEAG6HA4NUFR2Y0FVA2",
// ...
"transactions": [
{
"object": "payment.transactions",
"id": "PCI_DGV8C350XMXP2PDBHQS63W5000W9NN"
}
],
// ...
"updated": "2020-11-13T10:39:13+01:00",
"status": "created",
// ...
"payment_method": "paypal",
"trans_id": "40000537",
"iframe_url": "https://www.sandbox.paypal.com/checkoutnow?token=7T650704F18422052",
// ...
}

Now you need to direct the user to the iframe_url. This takes him to the PayPal page. After finishing the process there, he is directed back either to you success_url or to the failure failure_url.

Despite its name, you should not open the iframe_url within an Iframe ( <iframe> ):

  • 3-D Secure checks can leave the Iframe and switch to full-screen. In this case, the success (success_url) or failure URL (failure_url) of the shop is not opened inside the Iframe, but in the uppermost browser window (DOM window.top).

  • Some popular browsers have very strict same-origin restrictions for third party content, so that Cookie technology will not work inside Iframes. Most external authorisation flows cannot be completed.

In case you would also like to offer Sofort, please note that such payments are not allowed in Iframes at all.

When the user arrives at the success URL, the Smart Transaction is updated too. It has status approved now, and can be captured now. If auto_capture was enabled for this Smart Transaction, the status would be ok, received or collection. The payment ist alreay captured, and you can save the next API call.

When the user arrives at the failure URL, the Smart Transaction has status failed, and you must repeat the payment process.