Payment flow

Payment Management

A typical payment flow with the Nexpay API involves three main steps:

1. Submit a payment order

Send a POST /api/2/eurowallet/payments request to create a new outgoing payment.

2. Handle the response

---
title: 'Payment creation response handling' 
---
%%{ init: { 'flowchart': { 'curve': 'stepAfter' } } }%%
graph LR
    A(Payment create request):::shape --> B{HTTP timeout?};
    B:::shape -- No --> D{HTTP status};
    D -- 4xx --> F[Request denied]:::shapeDenied;
    D:::shape -- 200 OK --> E[Request accepted]:::shapeAccepted;
    D -- 5xx --> C[Recovery check]:::shapeWarning;
    B -- Yes --> C[Recovery check];
classDef shape fill:none,stroke:#475569;
classDef shapeWarning fill:none,stroke:#ffc310;
classDef shapeDenied fill:none,stroke:#f11e37;
classDef shapeAccepted fill:none,stroke:#349469;

Get acknowledgment that the system has successfully accepted the payment order (200 OK). Generally, in response to the POST /api/2/eurowallet/payments, you can receive three types of HTTP status codes:

• 200 OK - your payment order has been successfully created.
• 4XX - your request has been denied; check the returned error code, resolve the issue, and submit the request again.
• 5XX - an internal error has occurred; in this case, perform the recovery check described below to determine whether the payment order was created or not.

It may also be the case that your request times out. Since in this case you cannot be sure whether the payment order was created or not, you will also need to perform the recovery check.

3. Check execution status

Query the system to verify that the payment has been executed successfully. The status of a successfully created payment order can be checked in two ways:

• Webhook notifications - recommended for real-time updates, allowing your system to automatically receive payment status changes.
• Periodic status polling - by calling payment status endpoint at regular intervals to retrieve the current payment state.

Recovery check

Occasionally, your payment creation requests may time-out or return an HTTP 5XX status code. This can happen due to network instability, temporary system updates, downtime, or other unexpected factors.

In these situations, you cannot be certain whether your payment request was successfully processed or not. To avoid accidentally creating a duplicate payment, you must perform a recovery check.

In simple terms, the recovery check means verifying the payment status until you receive a definitive answer on whether the payment was created or was not created.

The recovery check can be performed in two ways: with or without using externalPaymentId.

The externalPaymentId is an optional parameter that can be sent in the POST /api/2/eurowallet/payments. It serves as a custom internal identifier shared between you and your end-customer, helping you track and reference payments across systems.

1. Recovery check using the same externalPaymentId (recommended)

This is the preferred and safest method.

If your original payment creation request contained the externalPaymentId, repeat the payment creation request using the same externalPaymentId until it succeeds. It is recommended to perform retries using an exponential back-off algorithm. Using the same externalPaymentId ensures that even if the initial request succeeded, a duplicate payment will not be created.

• If you receive paymentId and status, it means that the payment was created either as a part of the original, or current request.
• If repeated attempts continue to fail with 5XX errors or timeouts for a considerable amount of time, report the issue to your account manager or contact support at [email protected]

2. Recovery check without using the same externalPaymentId (not recommended)

This method should only be used if you cannot include the same externalPaymentId in subsequent requests.

Poll the payment status using the externalPaymentId or paymentId of the original request for X minutes.

• If a payment status is returned, the payment was successfully created and will be processed according to the returned status.
• If after X minutes, the payment cannot be found (error code 30000, message No payment found with given payment parameter), you may assume that the payment creation failed.
• If any other error is returned, verify your request correctness or report the issue to your account manager/contact support at [email protected]

Note: This approach does not guarantee that the payment will not be created after the X-minute polling period, although the likelihood is low and depends on the chosen value of X.

Repeated payment creation

A repeat attempt to make a payment should be made in the following cases:

• If in response to the payment creation request POST /api/2/eurowallet/payments, you received the 4XX HTTPS status code.
• If the original payment has been created but then rejected, i.e., GET /api/1/eurowallet/payments/status returned REJECTED status.
• If in response to the payment creation request POST /api/2/eurowallet/payments, you received the 5XX HTTPS status code or a time-out, which means that you need to perform the recovery check.

Please note that when attempting to create a payment again (regardless of the above reason), it is strongly recommended to use externalPaymentId.

Note: In all other cases, attempting to re-create a payment may result in a duplicate payment being created and, as a result, a loss of funds.