Introduction

We are constantly striving to make our API simpler, more intuitive and easier to integrate. We utilize REST architectural style with predictable URLs,
built-in HTTP features and HTTP verbs comprehensive for most HTTP clients.

All the API responses, including errors, are sent in JSON format. Again, we only use widespread HTTP response codes for the API error messages. The API only accepts requests sent over HTTPS, therefore any calls made through HTTP as well as requests without authentication will be rejected.

Upon registration with Bigwallet a new Merchant is provided with one or several terminals, each terminal being protected with separate credentials. A Merchant Terminal can operate in one of the two modes: Server-to-Server or Hosted Payment Page.

Hosted Payment Page mode

This mode implies that Customer is redirected to Bigwallet-hosted payment page to enter card details and perform payment. Being protected by Bigwallet PCI DSS certificate this mode is considered to be the most secure and enabled by default for all merchants. Merchant in its turn does not have to be PCI DSS compliant to use this mode.

When the card is not participating in 3D-Secure program then steps 7-9 are not applicable.

Server-to-Server mode

This mode implies that card data is collected by Merchant and then sent to Bigwallet for further processing.

Note

You should be fully PCI compliant in order to use Server-to-Server mode and perform initial payment request on your side as it requires collecting card data. Those not fully PCI compliant can use Hosted Payment Page to collect payment data securely.

Server-to-Server Flow for 3D-Secure Cards

Payment flow with 3D-Secure in Server-to-Server mode when card is enrolled to 3D-Secure program:

The obtained access_token should be provided in "Auhorization" HTTP header in subsequent API requests, e.g.:

Authorization: Bearer

Errors

Bigwallet uses conventional HTTP response codes to indicate the success or failure of an API request.

In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided
(e.g., a required parameter was omitted, a transaction declined, etc.), and codes in the 5xx range indicate an error with Bigwallet servers
(these are rare). In erroneous cases, server response will contain “error” object with detailed information about the error.

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., a card is declined), server return a 422 error code (“Unprocessable Entity”). To understand why a card is declined, refer to the list of result codes.

Create payment in Hosted Payment Page mode

In the following example a create transaction request is posted for merchant terminal operating in Hosted Payment Page mode.

The minimal payment request contains following fields:

amount – transaction amount

currency – code of the transaction currency

merchantTransactionId – Unique ID of the transaction assigned by Merchant

To proceed with the payment the Customer should be redirected to checkout URL. The self URL can be used to check transaction status via API while payment URL can be used by the Customer as a permanent transaction URL.

Create payment in Server-to-Server mode

In the following example a create transaction request is posted for merchant terminal operating in Server-to-Server mode. For payment methods other then CREDIT_CARD the request is the same as used in Hosted Payment Page mode. For CREDIT_CARD payment method the card data must be provided.

The minimal payment request contains following fields:

amount – transaction amount

currency – code of the transaction currency

merchantTransactionId – Unique ID of the transaction assigned by Merchant

If checkout link is present and state is IN_PROGRESS the Customer must be redirected to checkout URL to proceed with payment. The self URL can be used to check transaction status via API while payment URL can be used by the Customer as a permanent transaction URL.

Backoffice Operations

You can perform different types of backoffice operations using our server-to-server REST API.

Capture an authorization

Reverse an authorization (void)

Refund a payment

Capture an authorization

This operation is used to capture authorized funds. To use this operation, the original payment call must have the intent set to AUTHORIZE. A capture request is performed against a previously authorized payment transaction.

Response sample

Reverse an authorization (void)

This operation is used to release funds that the authorization holds. To use this operation, the original payment call must have the intent set to AUTHORIZE. A void request is performed against a previously authorized payment transaction.

Return Urls

When transaction processing is completed or cancelled, Customer is redirected back to the merchant’s website. Merchant may provide URLs to handle different use-cases. It may be configured via Merchant Portal.

Type

Description

Required

Example

ShopUrl

The base URL of the shop. It will be used if more specific urls not specified.

Yes

https://shop.example.com

ReturnSuccessUrl

Customer will be redirected to this URL when transaction is AUTHORIZED or COMPLETED (depending on Payment Intent)

No

/checkout/${merchantTransactionId}?success

ReturnFailureUrl

Customer will be redirected to this URL when transaction is DECLINED

No

/checkout/${merchantTransactionId}?decline

ReturnHoldUrl

Customer will be redirected to this URL when transaction is ON_HOLD (should be captured manually)

No

/checkout/${merchantTransactionId}?on_hold

ReturnCancelUrl

Customer will be redirected to this URL when he/she clicks on the “Cancel” on the hosted payment page

No

/checkout/${merchantTransactionId}?cancel

ReturnSuccessUrl, ReturnFailureUrl and ReturnCancelUrl must be relative to ShopUrl or must be in the same domain. URLs may contain a placeholders (see Url Placeholders).

URL Placeholders

URLs may contain placeholders which will be resolved before actual redirect.

Merchant Notifications

Payment - Webhooks

Bigwallet servers may notify merchants automatically when transaction status is updated by making HTTP requests to merchants’ web server. This is called webhooks. A webhook listener is a server that listens for incoming HTTP POST notification messages that are triggered when events occur.

Payment - Responding to a webhook

To acknowledge that you received the webhook, your server should return a 200 or 201 HTTP status code. Any other information returned in the response headers or response body will be ignored.

Any response code other then 200 and 201, including 3xx codes, will indicate to Bigwallet that the webhook is not received. In this case Bigwallet can send another webhook after some time. Webhook will be repeated 9 times - after 1, 5, 15, 30, 60, 120, 180, 360 and 720 minutes. Repeated webhooks are optional, consult your integration manager.

Payment - Email Notifications

Bigwallet may send email notifications when transaction status is changed.

Notification email will be sent when transaction reaches one of the following states:

COMPLETED

ON_HOLD (when Payment Intent was SALE)

AUTHORIZED (when Payment Intent was AUTHORIZE)

DECLINED

CANCELLED

VOIDED

PARTIALLY_REFUNDED

REFUNDED

TIMEOUT

Merchant should provide email address for notifications during integration process.

Identification - Webhooks

Bigwallet servers may notify merchants automatically when identification transaction status is updated by making HTTP requests to merchants’ web server. This is called webhooks. A webhook listener is a server that listens for incoming HTTP POST notification messages that are triggered when events occur.

The Merchant status URL shown to the customer after a completed or declined identification Example : "http://example.com/12345abcde/status"

string

webhookUrlrequired

The Merchant webhook URL which will be called when the identification process is completed. Bigwallet will sent a KYCResponse object as payload. The payload will contain the registered customer details Example : "http://example.com/12345abcde/webhook"

RefundRequest

Name

Description

Schema

amountrequired

Amount to refund in the same currency as original payment.Can’t be greater than amount of the original payment transaction minus already refunded amount. Minimum value : 1.0E-18Maximum value : 999999.99