Payments

Flow diagram

The following image shows the positive payment flow:

Flow of statuses

The following image depicts all statuses that a payment can take and possible transitions between them:

Code	Description
NEW	Is only valid for payment without a selected payment method. This status means that the payment has been accepted by Paynow and Paynow is waiting for the user to select a payment method.
PENDING	Payment method has been selected and Paynow is waiting for the buyer to complete the payment. Once the payment method has been selected, the buyer cannot change it.
CONFIRMED	Payment has been successfully processed by Paynow and the money has been transferred to the recipient's account.
REJECTED	Payment was not authorized by the buyer.
ERROR	Problem occurred during the payment process.
EXPIRED	Validity time of payment has passed and the payment is no longer possible.
ABANDONED	Buyer retried to complete ERROR or REJECTED payment; new payment has new id and is connected to order.

Notice

Any payment remaining in NEW or PENDING status for 10 days will be automatically re-processed to EXPIRED status.

Don't forget

To use retry mechanism with ABANDONED, configuration option must be enabled in the Merchant Panel.

Make a payment

For purposes of this guide, we will assume that your keys are:

• Api-Key = 97a55694-5478-43b5-b406-fb49ebfdd2b5
• Signature-Key = b305b996-bca5-4404-a0b7-2ccea3d2b64b

Step 1: Prepare a payment request message. Throughout this example, we'll use a simple message containing only required fields which look as follows:

{
  "amount": 45671,
  "externalId": "234567898654",
  "description": "Test transaction",
  "buyer": {
    "email": "jan.kowalski@melements.pl"
  }
}

The amount specified should be in the smallest unit of the payment currency ( grosz in the case of PLN). It means that the above request defines a payment for 456.71 PLN. Each payment request must contain an 'externalId' that is assigned by the Merchant during creation. It uniquely identifies the payment on the Merchant's side. The description field can contain any text that helps to identify the payment. The buyer field must include, at a minimum, the email address of the Buyer making the payment and may contain other fields to describe the Buyer.
For a complete specification for the payment request message, go to API reference.

Notice

In order to use certain payment methods (ex. PayPo) the Buyer field must also include the address field with billing and shipping fields containing at least the street, zipcode and city of the buyer as shown here.

Step 2: Attach Api-Key header with the value of Api-Key available in the Merchant Panel.

Step 3: Calculate signature and attach it as the Signature header. For given example correct signature is ZBlr1Eg2n28HHOkRkh1LyOD60xl0MQguYHDgJRy7Hps=

Important

If you are trying to calculate the signature from the example in your code and are getting a different result, make sure that your JSON message is formatted the same way as the message in the example, i.e. with four-space indentation and no newline character at the end.

Step 4: Generate random string with maximum length of 45 characters for an Idempotency-Key header.

Step 5: Make a POST with prepared message on payment request endpoint

curl --request POST 'https://api.sandbox.paynow.pl/v3/payments' \
-H 'Content-Type: application/json' \
-H 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
-H 'Signature: lGOrwYvoRYwWcKSEtE/YDn8go1w/i5dj8Rv/ytIvXVE=' \
-H 'Idempotency-Key: 59c6dd26-f905-487b-96c9-fd1d2bd76885' \
--data-raw '{
    "amount": 45671,
    "externalId": "234567898654",
    "description": "Test transaction",
    "buyer": {
        "email": "jan.kowalski@melements.pl"
    }
}'

Notice

Bear in mind, that the request must include Host and Accept headers as described here. They are not listed above explicitly as the curl command includes them by default.

Step 6: Handle the returned response:

{
  "redirectUrl": "https://paywall.sandbox.paynow.pl/NOLV-8F9-08K-WGD?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwb3NJZCI6IjEwMDAiLCJwYXltZW50SWQiOiJOT0xWLThGOS0wOEstV0dEIiwiZXhwIjoxNTU0ODEzMTY4fQ.71TLjI8U8p0c_hhC1Nj3cAPU3mtzYW4ylGo8qVeB18o",
  "paymentId": "NOLV-8F9-08K-WGD",
  "status": "NEW"
}

The response contains the URL that the Buyer should be redirected to, ID of the payment generated by Paynow, and the current status of the payment. Returned paymentId should be saved by Merchant for further reference.

Step 7: Redirect the Buyer to the address specified in the response. The Buyer will be redirected to Paynow paywall, which guides her/him through the payment process. After finishing the payment, the Buyer will be redirected to a URL provided by the Merchant during the configuration as return-url. The return-url will contain additional URL parameters: paymentId and paymentStatus. To see more details, please refer to the Flow Diagram

Step 8: During the payment process, Paynow delivers notifications about the current payment status each time the status is changed.

In case of failed payment, a similar message will be delivered containing REJECTED or ERROR status instead depending on the reason for failure.

Payment recovery

Paynow offers payments recovery feature for payments on PENDING, REJECTED or ERROR status. Recovery is available for all integrations. To support payment recovery you have to implement ABANDONED from flow of statuses. All payments are connected by externalId from initial payment.

How it works:

1. Submit Create a payment request.
2. Reject the payment.
3. From status page use Retry the payment option. Paynow will create payment with new paymentId.
4. Complete the payment with authorization.
5. Check the payment status or accept notification with new paymentId. The externalId will be the same like for first initial payment.