Prerequisites

Before you read this guide, you should understand:

Prerequisites for PayPal Payment

In order to use PayPal payments it is needed that our application can:

  • Create transactions and manage the payment process
  • Receive information about the progress or problems

Thus you must set up your PayPal account this way:

  1. Create App credentials for our software on the PayPal developer website at https://developer.paypal.com/.
  2. Restrict the access of the App credentials (details below).
  3. Set up webhook notifications for the App (details below).
  4. Register the App credentials in our secuOffice under "Payment" » "Settings" » "PayPal".

Needed permissions for the App credentials:

  • "Accept payments"

If you use subscriptions grant furthermore:

  • "Billing agreements" (inside "Accept payments" » "Advanced options")

Webhook URLs:

Needed webhook events:

  • "Payment Capture Completed"
  • "Payment Capture Refunded"
  • "Payment Capture Reversed"

If you use subscriptions additionally these events:

  • "Billing Subscription Cancelled"

  • "Billing Subscription Expired"

  • "Billing Subscription Re-Activated"

  • "Billing Subscription Suspended"

  • "Payment Sale Completed"

  • "Payment Sale Refunded"
  • "Payment Sale Reversed"

Please ask our help desk to guide you through this process if this is not intuitive for you.

Authorise the Payment

Do not test PayPal payments with non-demo transactions on our test servers. This will result in live transactions on PayPal side. Make sure you always use demo transactions to test PayPal, as these will go to the PayPal sandbox. In future our test servers may deny the authorisation of non-demo Smart Transactions for PayPal.

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.secuconnect.com
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.

Capture the Payment

The way to capture an authorised payment is the same for all payment methods. If you have already studied this for invoice or direct debit payment, you will not find any new details.

In order to start the authorized Smart Transaction, you only need to call POST Smart/Transactions/STX_xxx/start.

Request
POST /api/v2/Smart/Transactions/STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2/start HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

If everything is fine, the API responds with 200 OK:

Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
// ...
"transactions": [
{
"object": "payment.transactions",
"id": "PCI_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7"
}
],
"created": "2020-03-27T10:55:23+01:00",
"updated": "2020-03-27T10:56:41+01:00",
"status": "ok",
// ...
}

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 of invoice payment you need to mark the actual delivery. This is to know the payment has become due, and to calculate the due date.

In the background the PayPal order is also started.

See Also

Further information:

Other payment methods: