English

Payment flow

Payment Request Initiation

Every funds collection flow in a checkout starts with Payment Request initiation, either it uses a recurring billing or just a standard in-browser payment by user. We always start with Payment Request initiation and then process it in different ways.

Payment Request initiation is deadly simple. You have to create a payment request resource via Recurring Billing API and after that either redirect user to authorization url provided in response or if you are using recurring billing process payment manually.

To initiate(create) Payment Request you have to use either our library or make a call using Recurring Billing API specification.

Please visit Recurring Billing API specification page to get list of required parameters as well as endpoint path and examples to create Payment Request. Or use any of our libraries, which can be found on Libraries page.

Info Please note, that if you want to use recurring billing for next payments, you have to use token_strategy parameter when initiating first request for your user, then you will receive token on payment confirmation we describe in "Payment Confirmation" step.
That token will be used for recurring billing.
Info When initiating Payment Request with token_strategy, only payments that support token functionality are allowed and has to be specified explicitly via method_key parameter (ex. card)
Info Domain, which API calls are made to is provided together with credentials

After you successfully create a resource, you will receive authorization_url in response. Use it if you want to redirect user to payment form.

And that's all! Now all you need is to wait until user pays, and then proceed with Payment Confirmation step described below

Payment confirmation

After successful payment, either it was finished via browser by user or captured via api in case of recurring billing, our service will send a callback to url you provided via callback_url when initiated a Payment Request.

That callback will contain notification_id parameter in POST body which will be used later on.

Please visit Notification Event API specification page for detailed specification. Or use any of our libraries, which can be found on Libraries page.

After you receive such a callback. You have to do a call to Notification Event API and receive data related to that notification by notification_id. Data may vary, but in case of payment confirmation which is described here, you will get event parameter named payment_request.captured.

Data in data parameter will be an array with key payment_request and will have value of same structure as Payment Request resource which is described in Recurring Billing API specification page. At this point you may get parameter called issued_token which will contain token for recurring billing. Check Payment Request status and make sure it is captured, after that you can confirm payment in your project.

Full flow examples

Standard Payment Request

Step 1

You make call to Recurring Billing API and initiate a new Payment Request via POST with json encoded body

Request
POST /checkout/rest/v1/payment-requests HTTP/1.1
Host: checkout-eu-a.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="ikVkAqVe4Yp5JZ/VckAgZQTVOBaDItb1H2GWWP5INSg=", ext="body_hash=A3KDuD2IfzzJeEtoJFYIZ%2B2UIZwMmEnLNpSKpZZVMLQ%3D"
{
    "business_id": "LcKB4rs-pNVLgQKxZTaGzfZRAuiQPuyE",
    "order_id": "12345446",
    "price": {
        "amount": "10.00",
        "currency": "EUR"
    },
    "description": "Payment for goods on order 12345446 on the website https://shop.com.",
    "method_key": "card",
    "payer": {
        "email": "payer@email.com"
    },
    "locale": "en",
    "accept_url": "https://shop.com/accept-url",
    "cancel_url": "https://shop.com/cancel-url",
    "callback_url": "https://shop.com/callback-url"
}
Response body
{
    "id": "PRAHdH4r8NJtep-s8VRkWyKhv1GzP_oW",
    "payer": {
        "email": "payer@email.com"
    },
    "authorization_url": "https://checkout.paysera.com/PRAHdH4r8NJtep-s8VRkWyKhv1GzP_oW",
    "price": {
        "amount": "10.00",
        "currency": "EUR"
    },
    "locale": "en",
    "business_id": "LcKB4rs-pNVLgQKxZTaGzfZRAuiQPuyE",
    "order_id": "12345446",
    "unique_identifier": null,
    "valid_until": null,
    "description": "Payment for goods on order 12345446 on the website https://shop.com.",
    "method_key": "card",
    "method_country": null,
    "accept_url": "https://shop.com/accept-url",
    "cancel_url": "https://shop.com/cancel-url",
    "callback_url": "https://shop.com/callback-url",
    "affiliate_key": null,
    "parameters": null,
    "status": "new",
    "gateway_key": null,
    "token_strategy": null
}

Step 2

Redirect user to authorization_url from response.

Info Redirect only if you are not using recurring billing or it is first user's payment you will use recurring billing on.

Step 3

After user finishes process of payment we will send a notification_id in POST body to callback_url provided (ex. https://shop.com/callback-url will receive notification_id: ABcJDZe-rWzLgQKxZTamdfZRApsrPuyE)

Info User will be redirected to accept_url provided after payment processs finished.

Then you have to either check what inside and mark that notification as read, or mark that notification as read in one call. We suggest you to check first and mark after, but it's up to you.

Request
GET /notification/rest/v1/notifications/ABcJDZe-rWzLgQKxZTamdfZRApsrPuyE HTTP/1.1
Host: checkout-eu-a.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="3WhLKS7daZvTA0c/GP6H+ORnIo5WPDamhHRcUCtwTF0="
Response body
{
  "id": "ABcJDZe-rWzLgQKxZTamdfZRApsrPuyE",
  "event": "payment_request.captured",
  "status": "new",
  "data": {
    "id": "PRAHdH4r8NJtep-s8VRkWyKhv1GzP_oW",
    "payer": {
      "name": "John",
      "surname": "Doe",
      "full_name": "John Doe",
      "email": "payer@email.com",
      "account_number": "123456XXXXXX1234"
    },
    "authorization_url": "https://checkout.paysera.com/PRAHdH4r8NJtep-s8VRkWyKhv1GzP_oW",
    "price": {
      "amount": "10.00",
      "currency": "EUR"
    },
    "price_paid": {
      "amount": "10.00",
      "currency": "EUR"
    },
    "locale": "en",
    "business_id": "LcKB4rs-pNVLgQKxZTaGzfZRAuiQPuyE",
    "order_id": "12345446",
    "unique_identifier": null,
    "valid_until": null,
    "description": "Payment for goods on order 12345446 on the website https://shop.com.",
    "method_key": "card",
    "method_country": null,
    "accept_url": "https://shop.com/accept-url",
    "cancel_url": "https://shop.com/cancel-url",
    "callback_url": "https://shop.com/callback-url",
    "affiliate_key": null,
    "parameters": null,
    "status": "captured",
    "gateway_key": "card",
    "token_strategy": null
  }
}

As you can see you get notification data about Payment Request. Status is captured, that means that payment is successfully finished.
We provide additional information about payer such as name, surname, card number if those are available.

After processing data you have to mark notification as read, or callback will be repeated few times until you mark it as read.
To do so you have to make API call to Notification Event API

Request
PUT /notification/rest/v1/notifications/ABcJDZe-rWzLgQKxZTamdfZRApsrPuyE/read HTTP/1.1
Host: checkout-eu-a.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="MfSmVrzzTDQUaVQmYiabdHtrhH089yCxg6zugsY/c8g="
Response body
{
  "id": "ABcJDZe-rWzLgQKxZTamdfZRApsrPuyE",
  "event": "payment_request.captured",
  "status": "read",
  "data": {
    "id": "PRAHdH4r8NJtep-s8VRkWyKhv1GzP_oW",
    "payer": {
      "name": "John",
      "surname": "Doe",
      "full_name": "John Doe",
      "email": "payer@email.com",
      "account_number": "123456XXXXXX1234"
    },
    "authorization_url": "https://checkout.paysera.com/PRAHdH4r8NJtep-s8VRkWyKhv1GzP_oW",
    "price": {
        "amount": "10.00",
        "currency": "EUR"
    },
    "price_paid": {
      "amount": "10.00",
      "currency": "EUR"
    },
    "locale": "en",
    "business_id": "LcKB4rs-pNVLgQKxZTaGzfZRAuiQPuyE",
    "order_id": "12345446",
    "unique_identifier": null,
    "valid_until": null,
    "description": "Payment for goods on order 12345446 on the website https://shop.com.",
    "method_key": "card",
    "method_country": null,
    "accept_url": "https://shop.com/accept-url",
    "cancel_url": "https://shop.com/cancel-url",
    "callback_url": "https://shop.com/callback-url",
    "affiliate_key": null,
    "parameters": null,
    "status": "captured",
    "gateway_key": "card",
    "token_strategy": null
  }
}

As you can see response is almost identical(that's why you can just read it without pre-reading) as when just getting notification data, except that this time status is read, that identifies that no more callbacks about this notification will be sent from our system

Payment Request for recurring billing

Payment Request initiation for recurring billing is almost same, except few things:

  • In step 1 additional parameter token_strategy has to be provided with value required
    • {
    "business_id": "LcKB4rs-pNVLgQKxZTaGzfZRAuiQPuyE",
    "order_id": "12345446",
    "price": {
        "amount": "10.00",
        "currency": "EUR"
    },
    "description": "Payment for goods on order 12345446 on the website https://shop.com.",
    "method_key": "card",
    "payer": {
        "email": "payer@email.com"
    },
    "locale": "en",
    "accept_url": "https://shop.com/accept-url",
    "cancel_url": "https://shop.com/cancel-url",
    "callback_url": "https://shop.com/callback-url",
    "token_strategy": "required"
}
  • In step 3 you will receive issued_token parameter containing token that you will use in recurring billing flow described on Recurring billing page 
    • {
    "id": "ABcJDZe-rWzLgQKxZTamdfZRApsrPuyE",
    "event": "payment_request.captured",
    "status": "read",
    "data": {
      "id": "PRAHdH4r8NJtep-s8VRkWyKhv1GzP_oW",
      "payer": {
        "name": "John",
        "surname": "Doe",
        "email": "payer@email.com"
      },
      "authorization_url": "https://checkout.paysera.com/PRAHdH4r8NJtep-s8VRkWyKhv1GzP_oW",
      "price": {
        "amount": "10.00",
        "currency": "EUR"
      },
      "locale": "en",
      "business_id": "LcKB4rs-pNVLgQKxZTaGzfZRAuiQPuyE",
      "order_id": "12345446",
      "unique_identifier": null,
      "valid_until": null,
      "description": "Payment for goods on order 12345446 on the website https://shop.com.",
      "method_key": "card",
      "method_country": null,
      "accept_url": "https://shop.com/accept-url",
      "cancel_url": "https://shop.com/cancel-url",
      "callback_url": "https://shop.com/callback-url",
      "affiliate_key": null,
      "parameters": null,
      "status": "captured",
      "gateway_key": "card",
      "token_strategy": "required",
      "issued_token": "vLUGdTtnDjQs7Yv0fjYQyYfG60m"
    }
}

Payment Request for recurring billing without transfer of funds

This type of payment request allows you to receive a token for future payments without taking any funds from client.

  • In step 1 additional parameter token_strategy has to be provided with value required
  • In addition to that refund_on_capture has to be provided with value true
    • {
    "business_id": "LcKB4rs-pNVLgQKxZTaGzfZRAuiQPuyE",
    "order_id": "12345446",
    "price": {
        "amount": "10.00",
        "currency": "EUR"
    },
    "description": "Payment for goods on order 12345446 on the website https://shop.com.",
    "method_key": "card",
    "payer": {
        "email": "payer@email.com"
    },
    "locale": "en",
    "accept_url": "https://shop.com/accept-url",
    "cancel_url": "https://shop.com/cancel-url",
    "callback_url": "https://shop.com/callback-url",
    "token_strategy": "required",
    "parameters": {
        "refund_on_capture": true
    },
}
  • In step 3 you will receive issued_token parameter containing token that you will use in recurring billing flow described on Recurring billing page 
    • {
    "id": "ABcJDZe-rWzLgQKxZTamdfZRApsrPuyE",
    "event": "payment_request.checkout_token_issued",
    "status": "read",
    "data": {
      "id": "PRAHdH4r8NJtep-s8VRkWyKhv1GzP_oW",
      "payer": {
        "name": "John",
        "surname": "Doe",
        "email": "payer@email.com"
      },
      "authorization_url": "https://checkout.paysera.com/PRAHdH4r8NJtep-s8VRkWyKhv1GzP_oW",
      "price": {
        "amount": "10.00",
        "currency": "EUR"
      },
      "locale": "en",
      "business_id": "LcKB4rs-pNVLgQKxZTaGzfZRAuiQPuyE",
      "order_id": "12345446",
      "unique_identifier": null,
      "valid_until": null,
      "description": "Payment for goods on order 12345446 on the website https://shop.com.",
      "method_key": "card",
      "method_country": null,
      "accept_url": "https://shop.com/accept-url",
      "cancel_url": "https://shop.com/cancel-url",
      "callback_url": "https://shop.com/callback-url",
      "affiliate_key": null,
      "parameters": {
        "refund_on_capture": true
      },
      "status": "canceled",
      "gateway_key": "card",
      "token_strategy": "required",
      "issued_token": "vLUGdTtnDjQs7Yv0fjYQyYfG60m"
    }
}