Documentation

Server-to-Server mode

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

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

1. Customer initiates checkout on Merchant's Site and enters Card details (1)
2. Merchant sends Payment Request with card details to BigWallet Payments (2)
3. BigWallet Payments verifies 3D-Secure enrollment status of the card (3)-(4)
4. BigWallet Payments returns Payment Response to Merchant (5)
5. If card is 3DS enrolled, customer must be redirected to URL provided in Payment Response to complete 3DS authentication (6-8)
6. BigWallet Payments sends Authorization requests to Acquirer Bank and process response (9-10)
7. If card is 3DS enrolled, customer is redirected to Merchant result page (11)
8. BigWallet Payments sends webhook with transaction status to Merchant (12)

The payment flow is a bit different when card is not enrolled to 3D-Secure program:

1. Customer initiates checkout on Merchant’s Site (1)
2. Merchant collects card details and sends Payment Request to BigWallet Payments via BigWallet Payments API: POST /payments (2)
3. BigWallet Payments saves payment request and verifies 3D-Secure enrollment status of the card (3)-(4)
4. Since the Card is not enrolled to 3D-Secure program BigWallet Payments authorizes and, optionally, captures the payment transaction in the Acquirer Bank (5)-(6) without any interaction with the Customer.
5. After processing complete, BigWallet Payments invokes a WebHook URL asynchronously on the Merchant Site (8)

©2016-2019 bigwpay.com

Quickstart

With each API call, you must set request headers including an OAuth 2.0 access token.

Use the OAuth request to get an access token for use with your subsequent API calls. Include the terminalKey:terminalSecret as your Basic Auth credential

Sample request command:

curl -v https://bigwpay.com/auth/token \
  -X GET \
  -H "Accept: application/json" \
  -u ":" \
  -d "grant_type=client_credentials"

Sample response:

{
    "access_token": "f3ca90fc-f492-4ff3-872a-5f0b84a09445",
    "token_type": "bearer"
}

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

Authorization: Bearer 

©2016-2019 bigwpay.com

BigWallet Payments 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 Payments 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.

©2016-2019 bigwpay.com

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
• description – Description of the payment

Example:

{
    "amount": 12.98,
    "currency": "EUR",
    "merchantTransactionId": "ORDER-12345",
    "description": "Purchase 9 red roses"
}

If paymentMethod is not specified, the CREDIT_CARD will be used. For payment methods other then CREDIT_CARD the customer’s email address must be specified.

Example PayPal request:

{
    "paymentMethod": "PAYPAL",
    "amount": 12.98,
    "currency": "EUR",
    "merchantTransactionId": "ORDER-12345",
    "description": "Purchase 9 red roses",
    "customer": {
      "email": "john@example.com"
    }
}

Http request must contain the access_token obtained during authorization.

Full request command example:

curl -v https://bigwpay.com/api/v1/transactions \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer " \
  -d '{
        "intent": "SALE",
      	"amount": 115.01,
      	"currency": "USD",
      	"merchantTransactionId": "tx-d4345dd2a0e",
      	"description": "Test Purchase via PaymentPage",
      	"shippingAddress": {
          "line1": "12, Sunrise Street",
          "line2": "Office 1234",
      	  "city": "Fremont",
      	  "countryCode": "US",
      	  "postalCode": "94536",
      	  "state": "CA",
      	  "phone": "(123) 456-7890",
      	  "recipientName": "John Smith"
        },
        "customer": {
          "email": "john@example.com",
          "phone": "(123) 456-7890",
          "merchantCustomerId": "cus-123456",
          "locale": "en",
          "ip": "99.33.51.102"
        }
      }'

Response example:

{
    "id": "9771fe8e1b4a4ce5b5f51c8681b58985",
    "created": "2017-01-11T08:49:36.524Z",
    "updated": "2017-01-11T08:49:36.524Z",
    "state": "CREATED",
    "paymentMethod": "CREDIT_CARD",
    "amount": 115.01,
    "currency": "USD",
    "merchantTransactionId": "tx-d4345dd2a0e",
    "description": "Test Purchase via PaymentPage",
    "shippingAddress": {
        "line1": "12, Sunrise Street",
        "line2": "Office 1234",
        "city": "Fremont",
        "state": "CA",
        "postalCode": "94536",
        "countryCode": "US",
        "phone": "(123) 456-7890",
        "recipientName": "John Smith"
    },
    "links": [
        {
            "href": "https://bigwpay.com/api/v1/transactions/9771fe8e1b4a4ce5b5f51c8681b58985",
            "rel": "self"
        },
        {
            "href": "https://bigwpay.com/payment/c0b491d9-bb7e-440d-9b4e-5c232bf3a8b8",
            "rel": "payment"
        },
        {
            "href": "https://bigwpay.com/payment/c0b491d9-bb7e-440d-9b4e-5c232bf3a8b8",
            "rel": "checkout"
        }
    ]
}

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.

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
• description – Description of the payment
• card – element containing card data

Example:

{
    "amount": 12.98,
    "currency": "EUR",
    "merchantTransactionId": "ORDER-12345",
    "description": "Purchase 9 red roses",
    "card": {
        "pan": "4000 0000 0000 0408",
        "expiryMonth": 11,
        "expiryYear": 2023,
        "cardholder": "Mr. Holder",
        "cvv": "123"
    }
}

Http request must contain the access_token obtained during authorization.

Full request command example:

    curl -v https://bigwpay.com/api/v1/transactions \
      -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer " \
      -d '{
            "intent": "SALE",
          	"amount": 115.01,
          	"currency": "USD",
          	"merchantTransactionId": "tx-d4345dd2a0e",
          	"description": "Test Purchase in StS mode",
          	"shippingAddress": {
              "line1": "12, Sunrise Street",
              "line2": "Office 1234",
          	  "city": "Fremont",
          	  "countryCode": "US",
          	  "postalCode": "94536",
          	  "state": "CA",
          	  "phone": "(123) 456-7890",
          	  "recipientName": "John Smith"
            },
            "customer": {
              "email": "john@example.com",
              "phone": "(123) 456-7890",
              "merchantCustomerId": "cus-123456",
              "locale": "en",
              "ip": "99.33.51.102"
            },
            "card": {
              "pan": "4000 0000 0000 0408",
              "expiryMonth": 11,
              "expiryYear": 2023,
              "cardholder": "Mr. Holder",
              "cvv": "123",
              "billingAddress": {
                "line1": "required first line",
                "line2": "optional second line",
                "city": "Saratoga",
                "countryCode": "US",
                "postalCode": "95070",
                "state": "CA",
                "phone": "123456789"
              }
            }
          }'

Note that card.billingAddress, customer.email, customer.phone can be mandatory for your integration. Please consult BigWallet Payments customer support for details.

Response example:

    {
        "id": "9771fe8e1b4a4ce5b5f51c8681b58985",
        "created": "2017-01-11T08:49:36.524Z",
        "updated": "2017-01-11T08:49:36.524Z",
        "state": "IN_PROGRESS",
        "paymentMethod": "CREDIT_CARD",
        "amount": 115.01,
        "currency": "USD",
        "merchantTransactionId": "tx-d4345dd2a0e",
        "description": "Test Purchase in StS mode",
        "shippingAddress": {
            "line1": "12, Sunrise Street",
            "line2": "Office 1234",
            "city": "Fremont",
            "state": "CA",
            "postalCode": "94536",
            "countryCode": "US",
            "phone": "(123) 456-7890",
            "recipientName": "John Smith"
        },
        "links": [
            {
                "href": "https://bigwpay.com/api/v1/transactions/9771fe8e1b4a4ce5b5f51c8681b58985",
                "rel": "self"
            },
            {
                "href": "https://bigwpay.com/payment/c0b491d9-bb7e-440d-9b4e-5c232bf3a8b8",
                "rel": "payment"
            },
            {
                "href": "https://bigwpay.com/payment/c0b491d9-bb7e-440d-9b4e-5c232bf3a8b8/redirect",
                "rel": "checkout"
            }
        ]
    }

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.

©2016-2019 bigwpay.com

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

©2016-2019 bigwpay.com

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.

Request sample

    curl https://bigwpay.com/api/v1/transactions//actions/capture \
      -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer "

Response sample

©2016-2019 bigwpay.com

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.

Request sample

    curl https://bigwpay.com/api/v1/transactions//actions/void \
      -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer "

Response sample

    {
        "id": "d7993562260c4ec2904612e5aa787261",
        "created": "2017-01-10T09:37:43Z",
        "updated": "2017-01-10T09:37:56Z",
        "state": "VOIDED"
    }

©2016-2019 bigwpay.com

This operation is used to fully or partially refund COMPLETED payment. Several refunds can be created for one payment, but total refunded amount cannot exceed amount of initial payment transaction.

    curl https://bigwpay.com/api/v1/transactions//actions/refund \
      -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer " \
      -d '{
            "amount": 10,
            "comment":"Refund reason"
          }'

Response sample

    {
        "id": "801fb13afafb4db3b31d61617a29c930",
        "created": "2017-01-11T10:09:26.179Z",
        "updated": "2017-01-11T10:09:26.179Z",
        "state": "COMPLETED",
        "amount": 10,
        "currency": "USD",
        "description": "Refund reason",
        "paymentTransactionId": "b14d79b2ddd84a639499bfda64980de8",
        "links": [
            {
                "href": "https://bigwpay.com/api/v1/transactions/801fb13afafb4db3b31d61617a29c930",
                "rel": "self"
            }
        ]
    }

©2016-2019 bigwpay.com

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.

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

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

Following expressions are supported:

${merchantTransactionId} – Merchant transaction ID provided in Create Transaction operation

The URL https://www.example.com/payment/${merchantTransactionId}/success will be resolved to https://www.example.com/payment/ORDER-123/success for transaction with merchantTransactionId=ORDER-123

©2016-2019 bigwpay.com

Merchant Notifications

BigWallet Payments 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.

To create a webhook, merchant provide a webhook listener URL for corresponding merchant terminal in Merchant Portal.

It is required to use secure HTTP connection for webhooks. Please use https: schema in webhook URLs.

Webhooks are 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
• ERROR

For example, when the transaction state is changed from Merchant Portal, a TransactionChangedEvent is issued and webhook is triggered.

Webhooks will be sent whenever the state of the resource changes. Certain activity may lead to the same event being sent more than once.

Example webhook:

    POST /webhook HTTP/1.1
    Host: www.example.com
    Content-Type: application/json
    {
      "type": "TransactionChangedEvent",
      "operationType": "REFUND",
      "operationState": "COMPLETED",
      "created": "2017-05-19T08:27:49.402Z",
      "transaction": {
        "type": "REFUND",
        "id": "345e3802528841bea67dc76744b76ab8",
        "amount": 59.02,
        "currency": "USD",
        "created": "2017-05-19T08:27:49.199Z",
        "updated": "2017-05-19T08:27:49.402Z",
        "state": "COMPLETED",
        "description": "Refund request",
        "maskedPan": "400000...0002",
        "paymentTransactionId": "70eb665c254140558921dfd479a5f390",
        "merchantCustomerId": "cus-123456",
        "customerEmail": "andy@example.com",
        "customerAccountId": "paypal_user_123"
      }
    }

Example webhook for declined operation (note the error property):

    POST /webhook HTTP/1.1
    Host: www.example.com
    Content-Type: application/json
    {
        "type": "TransactionChangedEvent",
        "created": "2017-01-19T11:45:55.251Z",
        "operationType": "REFUND",
        "operationState": "DECLINED",
        "error": {
            "code": "06.40.000",
            "description": "General Decline by Bank"
        },
        "transaction": {
            "id": "96a8c187f15f4bc3a9f553abc4e2d714",
            "type": "PURCHASE",
            "created": "2017-01-18T13:32:14.543Z",
            "updated": "2017-01-19T11:45:55.161Z",
            "state": "PARTIALLY_REFUNDED",
            "amount": 119.32,
            "currency": "USD",
            "refundedAmount": 42.32,
            "maskedPan": "400000...0002",
            "merchantTransactionId": "MTID383057",
            "description": "Just purchase",
            "chargebackState": "CHARGEBACK_REFUNDED"
        }
    }

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 Payments that the webhook is not received. In this case BigWallet Payments 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.

©2016-2019 bigwpay.com

BigWallet Payments 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.

©2016-2019 bigwpay.com

BigWallet Payments 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.

To create a webhook, merchant provide a webhook listener URL in the Identification Login & Registration requests.

It is required to use secure HTTP connection for webhooks. Please use https: schema in webhook URLs.

Webhooks are sent when transaction reaches one of the following states:

• COMPLETED
• DECLINED

An IdentWebhookResponse object is sent when the Identification Merchant webhook is called.

Example webhook:

    POST /webhook HTTP/1.1
    Host: www.example.com
    Content-Type: application/json
    {
          "merchantTransactionId": "mtid_ZjQzMjM2Y2NhZTk1"
          "id": "6d353a24d1d24b49bf69fc0cb4d25b8a",
          "identToken": "6556-ffrxzxxryzn0ovki08ca",
          "merchantCustomerId": "mtid_ZjQzMjM2Y2NhZTk1",
          "transactionState": "COMPLETED",
          "resultCode": "00.00.000",
          "personData": {
              "id": "1111111112",
              "name": "Johan Hedberg",
              "address": {
                  "street": "Toringsgatan 41",
                  "city": "Stockholm",
                  "country": "SE",
                  "postalCode": "10121"
              },
              "phone": "+46701231231",
              "phones": [
                  {
                      "phone": "+46701231231",
                      "type": "MOBILE"
                  },
                  {
                      "phone": "+46701231232",
                      "type": "MOBILE"
                  },
                  {
                      "phone": "+4680111231233",
                      "type": "OTHER"
                  }
              ],
              "firstName": "Johan",
              "firstNames": [
                  "Johan",
                  "Kim",
                  "Kattla"
              ],
              "lastName": "Hedberg",
              "gender": "MALE"
          }
    }

Example webhook for declined identification transactions:

    POST /webhook HTTP/1.1
    Host: www.example.com
    Content-Type: application/json
    {
        "id": "13e29f7ff1774d3e96298b9ddcb3ebd7",
        "merchantCustomerId": "mtid_ZDc4YTQ3YmJhZDFj",
        "transactionState": "DECLINED",
        "resultCode": "09.40.016",
        "merchantTransactionId": "mtid_ZDc4YTQ3YmJhZDFj"
    }

Identification - 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 Payments that the webhook is not received.

©2016-2019 bigwpay.com

Testing Your Integration

We provide a demo environment so you may test your integration before going live.

Demo server host is https://bigwpay.online and the production server is https://bigwpay.com.

For DEMO server use:

• API Token URL https://app.bigwallet.online/auth/token
• API URL https://app.bigwallet.online/api/v1

For PRODUCTION server use:

• API Token URL: https://app.bigwpay.com/auth/token
• API URL: https://app.bigwpay.com/api/v1

See API Reference.

©2016-2019 bigwpay.com

Test cards should be used for integration purposes only. Real cards will not be accepted in test mode vice versa test cards will not be accepted on production.

There are a number of predefined cards that are accepted in in test mode. First 6 digits is the card BIN (Bank Identification Number). The only accepted BINs are:

Card authorization behavior on demo server is controlled by the digits in specific positions in the card number (PAN). Each position is responsible for behavior of particular operation.

Value “0” in particular position means the success of related operation. Other digits defines an error codes or operation statuses and usually means operation failure.

The last digit (n-0) is a control digit, calculated using Luhn algorithm (should be valid).

Let’s consider the card number (PAN) 4000000000000002:

Examples

©2016-2019 bigwpay.com

Behavior of post-authorization (back-office) operations (Confirm, Reversal, etc.) is controlled by transaction amount (in the currency of the transaction).

Any operation (confirm, reversal or refund) with amount less or equal to 200 will be successful. Any operation with amount greater than 400 will be declined.

©2016-2019 bigwpay.com

API Reference - BigWallet Payments Merchant API

The BigWallet Payments API uses HTTP methods and a RESTful endpoint structure. The API authorization framework is OAuth 2.0. You format requests in JSON and the APIs return JSON-formatted responses.

    Version : 2018-08-28

    Contact : BigWallet Payments Support Team
    Contact Email : support@bigwpay.com

    License : Apache 2.0
    License URL : https://www.apache.org/licenses/LICENSE-2.0.html
    Terms of service : https://bigwpay.com/terms

    Host : bigwpay.com
    Schemes : HTTPS

• auth : OAuth 2.0 Server API
• payments : Merchant Payments API
• payouts : Merchant Payouts API
• backoffice : Merchant Backoffice API

©2016-2019 bigwpay.com

Security

Get an access token by using the OAuth 2.0 client_credentials token grant type with your terminalKey:terminalSecret as your Basic Auth credentials

    Type : basic

With each API call, you must set request headers including an OAuth 2.0 access token

    Type : oauth2
    Flow : application
    Token URL : https://bigwpay.com/auth/token

©2016-2019 bigwpay.com

Paths

Customer profile - Create Customer

Customer profile - Request to create a Customer

Name : body
Flags : required
Type : Customer

• application/json

• application/json

• customerProfile

Example HTTP request

Request body

{
"email" : "john@example.com",
"phone" : "(123) 456-7890",
"merchantCustomerId" : "cus-123456",
"locale" : "en",
"ip" : "99.33.51.102",
"userAgent" : "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) CriOS/56.0.2924.75 Mobile/14E5239e Safari/602.1"
}

Example HTTP response

Response 400

{
"status" : "error",
"code" : 400,
"message" : "Bad Request"
}

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 409

{
"status" : "error",
"code" : 409,
"message" : "Customer is already registered"
}

Description

Customer profile - Update Customer

Parameters

Body parameter

Customer profile - Request to update Customer

Name : body
Flags : required
Type : Customer

Responses

Consumes

• application/json

Produces

• application/json

Tags

• customerProfile

Security

Example HTTP request

Request body

{
"email" : "john@example.com",
"phone" : "(123) 456-7890",
"merchantCustomerId" : "cus-123456",
"locale" : "en",
"ip" : "99.33.51.102",
"userAgent" : "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) CriOS/56.0.2924.75 Mobile/14E5239e Safari/602.1"
}

Example HTTP response

Response 400

{
"status" : "error",
"code" : 400,
"message" : "Bad Request"
}

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 404

{
"status" : "error",
"code" : 404,
"message" : "Customer Not Found"
}

Description

Customer profile - Find Customer

Parameters

Responses

Consumes

• application/json

Produces

• application/json

Tags

• customerProfile

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 404

{
"status" : "error",
"code" : 404,
"message" : "Customer Not Found"
}

Description

KYC Register Checks - Creates a Check Gambling Registry transaction. It verifies if the customer is registered in a Gambling related registry

Body parameter

Mandatory parameters: countryCode, firstName, lastName. Optional parameters: i.e. dateOfBirth

Name : body
Flags : required
Type : KYCRegisterChecksRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• kyc

Security

Example HTTP response

Response 401#

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Description

KYC PEP and Sanctions Check - Creates a Check Watch List transaction. It verifies if the customer is PEP (politically exposed person) and if he has any sanctions

Body parameter

Mandatory parameters: countryCode, firstName, lastName. Optional parameters: i.e. dateOfBirth

Name : body
Flags : required
Type : KYCRegisterChecksRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• kyc

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Description

KYC - Creates a Login transaction

Body parameter

KYC - Request to create a Login transaction

Name : body
Flags : required
Type : KYCLoginRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• kyc

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Description

KYC Register Checks - Creates a Lookup Person transaction

Body parameter

Mandatory parameters: countryCode, personalNumber. Optional parameters: i.e. phone

Name : body
Flags : required
Type : KYCRegisterChecksRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• kyc

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Description

KYC Register Checks - Creates a Match Ids transaction: i.e. try to match a ‘national personal number’ with a ‘registry person id’ to understand if they refer to the same customer

Body parameter

Mandatory parameters: countryCode, extSystemId1, extSystemId2

Name : body
Flags : required
Type : KYCRegisterChecksRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• kyc

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Description

KYC - Creates a Registration transaction

Body parameter

KYC - Request to create a Registration transaction

Name : body
Flags : required
Type : KYCRegisterRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• kyc

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Description

KYC Register Checks - Creates a Search Person transaction

Body parameter

Mandatory parameters: countryCode, firstName, lastName. Optional parameters: i.e. phone, dateOfBirth, personalNumber, city

Name : body
Flags : required
Type : KYCRegisterChecksRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• kyc

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Description

KYC Register Checks - Creates a Validate Address transaction

Body parameter

Mandatory parameters: addressLine1, postalCode, city, countryCode. Optional parameters: i.e. firstName, lastName, dateOfBirth, mobileNumber, personalNumber

Name : body
Flags : required
Type : KYCRegisterChecksRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• kyc

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Description

KYC Register Checks - Creates a Validate Person transaction

Body parameter

Mandatory parameters: addressLine1, postalCode, city, countryCode. Optional parameters: i.e. firstName, lastName, dateOfBirth, phone, personalNumber

Name : body
Flags : required
Type : KYCRegisterChecksRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• kyc

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Description

Creates new payout and optionally executes it

Body parameter

Request to create a new payout transaction. This feature is not available by default. Please contact your BigWallet Payments relationship manager for details.

Name : body
Flags : required
Type : PayoutRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• payouts

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 422

{
"error" : {
"status" : 400,
"code" : "01.20.000",
"message" : "Bad Request"
}
}

Description

Approve a payout with status ON_HOLD

Responses

Produces

• application/json

Tags

• payouts

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 409

{
"error" : {
"status" : 409,
"code" : "09.20.008",
"message" : "Transaction is Locked"
}
}

Response 422

{
"error" : {
"status" : 400,
"code" : "01.20.000",
"message" : "Bad Request"
}
}

Description

Cancel a payout with status CREATED

Responses

Produces

• application/json

Tags

• payouts

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 409

{
"error" : {
"status" : 409,
"code" : "09.20.008",
"message" : "Transaction is Locked"
}
}

Response 422

{
"error" : {
"status" : 400,
"code" : "01.20.000",
"message" : "Bad Request"
}
}

Description

Decline a payout with status ON_HOLD

Responses

Produces

• application/json

Tags

• payouts

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 409

{
"error" : {
"status" : 409,
"code" : "09.20.008",
"message" : "Transaction is Locked"
}
}

Response 422

{
"error" : {
"status" : 400,
"code" : "01.20.000",
"message" : "Bad Request"
}
}

Description

Execute a payout with status CREATED

Responses

Produces

• application/json

Tags

• payouts

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 409

{
"error" : {
"status" : 409,
"code" : "09.20.008",
"message" : "Transaction is Locked"
}
}

Response 422

{
"error" : {
"status" : 400,
"code" : "01.20.000",
"message" : "Bad Request"
}
}

Description

Fetch complete list of result codes

Responses

Response 200

Produces

• application/json

Tags

• info

Description

Creates new payment transaction

Body parameter

Request to create a new payment transaction

Name : body
Flags : required
Type : PaymentRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• payments

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 422

{
"error" : {
"status" : 400,
"code" : "01.20.000",
"message" : "Bad Request"
}
}

Description

Fetch list of transactions

Responses

Response 200

meta

Produces

• application/json

Tags

• backoffice
• payments

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Description

Fetch data of transaction

Parameters

Responses

Produces

• application/json

Tags

• backoffice
• payments

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 404

{
"status" : "error",
"code" : 404,
"message" : "Transaction Not Found"
}

Description

Capture authorized payment.

Please ensure to send HTTP header Content-Length: 0 and not send HTTP header Content-Type.

Parameters

Responses

Produces

• application/json

Tags

• backoffice
• payments

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 404

{
"status" : "error",
"code" : 404,
"message" : "Transaction Not Found"
}

Response 409

{
"error" : {
"status" : 409,
"code" : "09.20.008",
"message" : "Transaction is Locked"
}
}

Response 422

{
"error" : {
"status" : 400,
"code" : "01.20.000",
"message" : "Bad Request"
}
}

Description

Create Payout using card from payment transaction

Parameters

Body parameter

Request to create payout for Purchase transaction

Name : body
Flags : required
Type : PayoutForPurchaseRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• payouts

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 404

{
"status" : "error",
"code" : 404,
"message" : "Transaction Not Found"
}

Response 409

{
"error" : {
"status" : 409,
"code" : "09.20.008",
"message" : "Transaction is Locked"
}
}

Response 422

{
"error" : {
"status" : 400,
"code" : "01.20.000",
"message" : "Bad Request"
}
}

Description

Refund captured payment

Parameters

Body parameter

Request for refund payment transaction

Name : body
Flags : required
Type : RefundRequest

Responses

Consumes

• application/json

Produces

• application/json

Tags

• backoffice
• payments

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 404

{
"status" : "error",
"code" : 404,
"message" : "Transaction Not Found"
}

Response 409

{
"error" : {
"status" : 409,
"code" : "09.20.008",
"message" : "Transaction is Locked"
}
}

Response 422

{
"error" : {
"status" : 400,
"code" : "01.20.000",
"message" : "Bad Request"
}
}

Description

Void authorized payment

Please ensure to send HTTP header Content-Length: 0 and not send HTTP header Content-Type.

Parameters

Responses

Produces

• application/json

Tags

• backoffice
• payments

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

Response 404

{
"status" : "error",
"code" : 404,
"message" : "Transaction Not Found"
}

Response 409

{
"error" : {
"status" : 409,
"code" : "09.20.008",
"message" : "Transaction is Locked"
}
}

Response 422

{
"error" : {
"status" : 400,
"code" : "01.20.000",
"message" : "Bad Request"
}
}

Description

Fetch transaction operations history

Parameters

Responses

Produces

• application/json

Tags

• backoffice
• payments

Security

Example HTTP response

Response 401

{
"error" : "invalid_token",
"error_description" : "Access token is not found"
}

GET /auth/token

Description

Retrieve an access token for use with your API calls

Parameters

Responses

Produces

• application/json

Tags

• auth

Security

©2016-2019 bigwpay.com

Definitions

This is abstract type – definition of common properties used by resource responses

This is abstract type – definition of common properties used by PurchaseTransaction, RefundTransaction and PayoutTransaction

Type : enum (PAYMENT_PAGE, SERVER_TO_SERVER)

The billing address is the address associated with payment card

Payment card. Must be sent in server-to-server requests when merchant has PCI DSS level 1 compliance. Must be omitted in payment page requests.

Card Brand

Type : enum (VISA, MASTERCARD, MAESTRO, MIR, UNKNOWN)

Chargeback state of the PURCHASE transaction

Type : enum (CLAIM, CHARGEBACK_WON, CHARGEBACK_LOST, CHARGEBACK_REFUNDED)

ISO 4217 currency code, crypto currency code (XBT is used for BTC, XTH is used for ETH to avoid conflict with fiat currency)

Type : enum (CNY, EUR, GBP, RUB, USD, XBT, B2BX, BCH, DOGE, XTH, USDT, ADA, LTC, XLM, XRP, EOS, BAT, XMR)

If present in the response, indicates that requested operation has not been completed successfully.

Polymorphism : Composition

If present in the response, indicates that requested operation has not been completed successfully.

Polymorphism : Composition

KYC - defines properties of the customer’s address

KYC - defines properties of the Login request transaction.

A list of phone numbers with the type.

KYC - defines properties of the Login/Registration transaction response.

KYC Register Checks - defines properties of the request transaction.

KYC - defines properties of the Registration request transaction.

KYC - defines properties of the transaction response. Fields always present: id, merchantTransactionId, transactionState, resultCode, customer.merchantCustomerId

KYC provider code

Type : enum (ENTERCASH, ZIGNSEC, NASPAY)

The transaction status

Type : enum (COMPLETED, DECLINED)

The object represents HATEOAS link. href attribute defined an actual URL. Link type (the rel attribute) can be one of the following types:

• self – URL of the transaction for access via API only
• payment – link can be used by the Customer as stable transaction URL
• checkout – If present then the Merchant should redirect the Customer to this URL to proceed with payment/payout
• payment_ref – link is valid for RefundResponse and can be used to access original payment transaction via API

Locale in ISO 639-1 format

Type : string

KYC - defines the match details

The match accuracy

Type : enum (LOW, MEDIUM, HIGH)

OperationType is used in transaction history response

Type : enum (IN_PROGRESS, COMPLETED, DECLINED, CANCELLED, TIMEOUT, ERROR)

OperationType is used in transaction history response

Type : enum (CREATE_PAYMENT, FILL_FORM, FILL_PREPARE_FORM, ANTIFRAUD, VERIFY_ENROLLMENT, CHECK_3DS, AUTHORIZE, CAPTURE, VOID, REFUND, CANCEL, DECLINE, CREATE_REFUND, EXECUTE_REFUND, PAYOUT, CREATE_PAYOUT, EXECUTE_PAYOUT, APPROVE_PAYOUT, DECLINE_PAYOUT, SET_CHARGEBACK_STATE, SET_STATUS)

Payment intent. Can be set to SALE for immediate funds withdrawal or AUTHORIZE to authorize a payment and withdraw funds from a Customer account later by executing capture operation.

Type : enum (AUTHORIZE, SALE)

Payment method. Select between various methods of payment – CREDIT_CARD is chosen by default.

Type : enum (CREDIT_CARD, SKRILL, PAYPAL, NETELLER, RPNPAY, PRZELEWY24, SOFORT, UPAYCARD, UPAYCARD_WIRE, JETON_WALLET, PAYSAFECARD, INTERAC, INTERAC_ETRANSFER, APCOPAY, CLEARSETTLE, ENTERCASH, TRUSTLY, TRUSTLY_PNP, INTERKASSA, KLUWP, ECOPAYZ, ASTROPAY, CASHIER, ECOMMPAY_TERMINAL, B2CRYPTO, CITADEL, EFTPAY, CRYPTOCURRENCY_EXTERNAL, BANKTRANSFER, VOGUEPAY, FLEXEPIN, BESTPAYCARD, COMMUNITY_BANK, CEP_BANK, SEPA, PAYTRIO, PAYRETAILERS, PAY2BEE, WECHAT, QQPAY, PAYSEC, QR, PAYMENTCENTER, REGULARPAY, VLOAD, BLACK42PAY, ECOMMPAY, ESTROPAY, GLOBEPAY, SAFECHARGE, B2BINPAY, STICPAY, MUCHBETTER, ENVOYPAY, PAYGIGA, SOLIDPAYMENTS, FASAPAY, MINERBOOKING, DIJIPAYS, TERREXA, ZIGNSEC_SWISH, THE_CHANGE, ZIMPLER, INTRORIX, ZOTAPAY, EASYEFT, NORDEA, IKAJO)

A request to create new payment transaction. Should contain at least amount, currency, merchantTransactionId and description fields

Polymorphism : Composition

A request to create new payout using data from Purchase transaction.

Payout intent. Use CREATE to store Payout request for later execution or EXECUTE to execute it immediately. If not provided then EXECUTE is chosen by default.

Type : enum (CREATE, EXECUTE)

A request to create new payout.

Polymorphism : Composition

Defines properties of the PAYOUT transaction.

Polymorphism : Inheritance
Discriminator : type

Defines properties of the PURCHASE transaction.

Polymorphism : Inheritance
Discriminator : type

Polymorphism : Composition

Defines properties of the REFUND transaction.

The amount of refund transaction is always in the same currency as original payment, and it can not exceed initial transaction amount minus already refunded amount.

Polymorphism : Inheritance
Discriminator : type

©2016-2019 bigwpay.com

A result code has the format dd.dd.ddd, i.e. 3 groups of numbers.

The result code consists of 3 parts:

• source – occurred error or 00 for successful result
• category – defines system layer on which the result has occurred or subgroup
• reason – specified details of the result

The codes are split into rough groups by the first number (source), then into more detailed sub-groups by the second number (category), then into the exact code by the third number (reason).

First group defines the source of the error:

Error Sources

Second group defines the category of the error:

Error Categories

The last group defines the exact reason of the error.

Some reasons are listed below:

Error Reasons

Example: 02.10.001 (Cancelled by Customer) means:

• 01 -> Customer
• 00 -> General
• 008 -> Cancelled

©2016-2019 bigwpay.com

You can pull a JSON with the result codes by sending a GET request to https://bigwpay.com/api/v1/resultCodes.

©2016-2019 bigwpay.com