Documentation

Here you’ll find all the relevant and necessary documents regarding integrations, testing and any relevant use case associated with your business shortly.

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.

payment-process-flow
  1. Customer initiates checkout on Merchant’s Site (1)
  2. Merchant sends Payment Request to BigWallet (2)
  3. BigWallet does authentication and authorization, validates parameters and returns Payment Page URL to Merchant (3)
  4. Merchant redirects Customer to BigWallet Payment Page (4)
  5. Customer enters Card details on Payment Page and submits form (5)
  6. BigWallet verifies 3D-Secure enrollment status of the card (6)-(7)
  7. If Card is enrolled for 3D-Secure program then Customer is redirected to Issuer Bank’s Access Control Page (8)(9)
  8. Customer confirms his identity and authorize transaction on the Issuer Bank’s Access Control Page (9)
  9. Bank Issuer redirects Customer back to BigWallet server when bank verification is completed (10)
  10. BigWallet sends Authorization requests with PaRes to Acquirer Bank (11). Customer is waiting on Compunet Status Page.
  11. Bigwallet processes Authorization response from Acquirer Bank (12)
  12. Bigwallet sends webhook with transaction status to Merchant (13)
  13. Bigwallet redurects customer to Result Page (14)

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:

payment-process-flow
  1. Customer initiates checkout on Merchant's Site and enters Card details (1)
  2. Merchant sends Payment Request with card details to Bigwallet (2)
  3. Bigwallet verifies 3D-Secure enrollment status of the card (3)-(4)
  4. Bigwallet 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 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 sends webhook with transaction status to Merchant (12)

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

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 via Bigwallet API: POST /payments (2)
  3. Bigwallet 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 authorizes and, optionally, captures the payment transaction in the Acquirer Bank (5)-(6) without any interaction with the Customer.
  5. After processing complete, Bigwallet invokes a WebHook URL asynchronously on the Merchant Site (8)

©2016-2019 bigwallet.com

Quikstart


Authorization

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 credentials.

Authorization Example

Sample request command:

curl -v https://bigwallet.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 

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
  • 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://bigwallet.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://bigwallet.com/api/v1/transactions/9771fe8e1b4a4ce5b5f51c8681b58985",
            "rel": "self"
        },
        {
            "href": "https://bigwallet.com/payment/c0b491d9-bb7e-440d-9b4e-5c232bf3a8b8",
            "rel": "payment"
        },
        {
            "href": "https://bigwallet.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.

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
  • 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://bigwallet.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 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://bigwallet.com/api/v1/transactions/9771fe8e1b4a4ce5b5f51c8681b58985",
            "rel": "self"
        },
        {
            "href": "https://bigwallet.com/payment/c0b491d9-bb7e-440d-9b4e-5c232bf3a8b8",
            "rel": "payment"
        },
        {
            "href": "https://bigwallet.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.

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.

Request sample

curl https://bigwallet.com/api/v1/transactions//actions/capture \
  -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": "COMPLETED"
}

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.

Request sample

curl https://bigwallet.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"
}

Refund a payment

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://bigwallet.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://bigwallet.com/api/v1/transactions/801fb13afafb4db3b31d61617a29c930",
            "rel": "self"
        }
    ]
}

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.

Following expressions are supported:

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

Example:

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 bigwallet.com

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.

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

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

©2016-2019 bigwallet.com

Testing Your Integration


Testing mode

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

Demo server host is https://bigwallet.online and the production server is https://bigwallet.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://bigwallet.com/auth/token
  • API URL: https://bigwallet.com/api/v1

See API Reference.

Test Cards

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:

BIN Payment Brand
400 000 VISA
401 200 VISA
490 763 VISA(Germany)
491 700 VISA(UK)
520 000 Master Card
555 500 Master Card
676 300 Maestro

Card Authorization Behavior

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.

Digit(n=length) Operation Value Result Description
n-3 Anti-Fraud 0 Success
2 Failure Transaction declined by anti-fraud
4 Authorized Transaction is risky. It will not be captured automatically due to high probability of fraud.
n-2 3D-Secure 0 Success Customer was successfully authenticated
1 Authentication Failed Customer failed or cancelled authentication. Transaction denied.
4 Not 3D-Secure Enrolled Cardholder not participating. Transaction will proceed as non-3D.
n-1 Authorization 0 Success Card authorization will be successful
1-9 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:

400000 000000 0 0 0 2
1-6 7-(n-4) n-3 n-2 n-1 n-0
BIN Not used, can be anything Ant-Fraud 3D-Secure Authorization Check digit

Examples

Card Number Description
4000 0000 0000 0002 3D-Secure Enrolled, Authorization Successful
4000 0000 0000 0010 3D-Secure Enrolled, Authorization will fail
4000 0000 0000 0101 3D-Secure Enrolled, 3D-Secure will fail
4000 0000 0000 2008 3D-Secure Enrolled, Anti-fraud will fail
4000 0000 0000 4004 3D-Secure Enrolled, Anti-fraud will cause transaction to be Authorized even if SALE was requested.
4000 0000 0000 0408 Non-3D-Secure, Authorization Successful
4000 0000 0000 0416 Non-3D-Secure, Authorization will fail

Testing Post-Authorization Operations

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

Operation 1 – 200 201 – 300 301 – 400 > 400
Refund Success Failure Failure Failure
Confirm (Capture) Success Success Failure Failure
Reversal (Void) Success Failure Failure Failure

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 bigwallet.com

API Reference

Bigwallet Merchant API

Overview

The Bigwallet 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 information

Version : 2018-08-28

Contact information

Contact : Bigwallet Support Team
Contact Email : support@bigwallet.com

License information

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

URI scheme

Host : bigwallet.com
Schemes : HTTPS

Tags

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

Security

basicSecurity

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

oauth2Security

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

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

Name Description
transactions Operations with transactions
payouts Payouts
kyc Customers registration and identification
customerProfiles Customers profiles management

Paths

POST /api/v1/customers/

Description

Customer profile - Create Customer

Body parameter

Customer profile - Request to create a Customer

Name : body
Flags : required
Type : Customer

Responses

HTTP Code Description Schema
201 Customer profile - Customer created. CustomerResponse
400 Invalid input CustomerError
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
409 Customer with the same details is already registered CustomerError

Consumes

  • application/json

Produces

  • application/json

Tags

  • customerProfile

Security

Type Name Scopes
oauth2 oauth2Security 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"
}

POST /api/v1/customers/{id}

Description

Customer profile - Update Customer

Parameters

Type Name Description Schema
Path id
required
Merchant Customer Id string

Body parameter

Customer profile - Request to update Customer

Name : body
Flags : required
Type : Customer

Responses

HTTP Code Description Schema
200 Customer profile - Customer updated. CustomerResponse
400 Invalid input CustomerError
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
404 Customer not found CustomerError

Consumes

  • application/json

Produces

  • application/json

Tags

  • customerProfile

Security

Type Name Scopes
oauth2 oauth2Security 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 404

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

GET /api/v1/customers/{id}

Description

Customer profile - Find Customer

Parameters

Type Name Description Schema
Path id
required
Merchant Customer Id string

Responses

HTTP Code Description Schema
200 Customer profile - Customer details. CustomerResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
404 Customer not found CustomerError

Consumes

  • application/json

Produces

  • application/json

Tags

  • customerProfile

Security

Type Name Scopes
oauth2 oauth2Security customerProfile

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"
}

POST /api/v1/kyc/checkGamblingRegistry

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

HTTP Code Description Schema
200 KYC - Check Gambling Registry transaction processed. Response fields: customer.matchDetails.isMatch and customer.matchDetails.data KYCResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Consumes

  • application/json

Produces

  • application/json

Tags

  • kyc

Security

Type Name Scopes
oauth2 oauth2Security kyc

Example HTTP response

Response 401#

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

POST /api/v1/kyc/checkWatchList

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

HTTP Code Description Schema
200 KYC - Check Watch List transaction processed. Response fields: customer.pepInfo and customer.sanctionsInfo KYCResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Consumes

  • application/json

Produces

  • application/json

Tags

  • kyc

Security

Type Name Scopes
oauth2 oauth2Security kyc

Example HTTP response

Response 401

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

POST /api/v1/kyc/login

Description

KYC - Creates a Login transaction

Body parameter

KYC - Request to create a Login transaction

Name : body
Flags : required
Type : KYCLoginRequest

Responses

HTTP Code Description Schema
201 KYC - Login transaction created. KYCRedirectResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Consumes

  • application/json

Produces

  • application/json

Tags

  • kyc

Security

Type Name Scopes
oauth2 oauth2Security kyc

Example HTTP response

Response 401

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

POST /api/v1/kyc/lookupPerson

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

HTTP Code Description Schema
200 KYC - Lookup Person transaction processed. Response fields: all customer, customer.address and customer.matchDetails.isMatch fields KYCResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Consumes

  • application/json

Produces

  • application/json

Tags

  • kyc

Security

Type Name Scopes
oauth2 oauth2Security kyc

Example HTTP response

Response 401

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

POST /api/v1/kyc/matchId

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

HTTP Code Description Schema
200 KYC - Match Ids transaction processed. Response fields: customer.matchDetails.isMatch KYCResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Consumes

  • application/json

Produces

  • application/json

Tags

  • kyc

Security

Type Name Scopes
oauth2 oauth2Security kyc

Example HTTP response

Response 401

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

POST /api/v1/kyc/register

Description

KYC - Creates a Registration transaction

Body parameter

KYC - Request to create a Registration transaction

Name : body
Flags : required
Type : KYCRegisterRequest

Responses

HTTP Code Description Schema
201 KYC - Registration transaction created. KYCRedirectResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Consumes

  • application/json

Produces

  • application/json

Tags

  • kyc

Security

Type Name Scopes
oauth2 oauth2Security kyc

Example HTTP response

Response 401

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

POST /api/v1/kyc/searchPerson

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

HTTP Code Description Schema
200 KYC - Search Person transaction processed. Response fields: customers (a list of customer entities) KYCResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Consumes

  • application/json

Produces

  • application/json

Tags

  • kyc

Security

Type Name Scopes
oauth2 oauth2Security kyc

Example HTTP response

Response 401

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

POST /api/v1/kyc/validateAddress

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

HTTP Code Description Schema
200 KYC - Validate Address transaction processed. Response fields: address.matchDetails.level, address.matchDetails.data KYCResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Consumes

  • application/json

Produces

  • application/json

Tags

  • kyc

Security

Type Name Scopes
oauth2 oauth2Security kyc

Example HTTP response

Response 401

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

POST /api/v1/kyc/validatePerson

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

HTTP Code Description Schema
200 KYC - Validate Person transaction processed. Response fields: customer.matchDetails.level, customer.matchDetails.data KYCResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Consumes

  • application/json

Produces

  • application/json

Tags

  • kyc

Security

Type Name Scopes
oauth2 oauth2Security kyc

Example HTTP response

Response 401

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

POST /api/v1/payouts

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 relationship manager for details.

Name : body
Flags : required
Type : PayoutRequest

Responses

HTTP Code Description Schema
201 Payout created PayoutResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
422 Operation is declined ErrorResponse

Consumes

  • application/json

Produces

  • application/json

Tags

  • payouts

Security

Type Name Scopes
oauth2 oauth2Security payouts

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"
  }
}

POST /api/v1/payouts/{id}/actions/approve

Description

Approve a payout with status ON_HOLD

Responses

HTTP Code Description Schema
200 Approve Payout was executed PayoutResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
409 Unexpected state of payment transaction: “Illegal Workflow State” or “Transaction is Locked” ErrorResponse
422 Operation is declined ErrorResponse

Produces

  • application/json

Tags

  • payouts

Security

Type Name Scopes
oauth2 oauth2Security payouts

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"
  }
}

POST /api/v1/payouts/{id}/actions/cancel

Description

Cancel a payout with status CREATED

Responses

HTTP Code Description Schema
200 Payout was cancelled PayoutResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
409 Unexpected state of payment transaction: “Illegal Workflow State” or “Transaction is Locked” ErrorResponse
422 Operation is declined ErrorResponse

Produces

  • application/json

Tags

  • payouts

Security

Type Name Scopes
oauth2 oauth2Security payouts

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"
  }
}

POST /api/v1/payouts/{id}/actions/decline

Description

Decline a payout with status ON_HOLD

Responses

HTTP Code Description Schema
200 Decline Payout was executed PayoutResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
409 Unexpected state of payment transaction: “Illegal Workflow State” or “Transaction is Locked” ErrorResponse
422 Operation is declined ErrorResponse

Produces

  • application/json

Tags

  • payouts

Security

Type Name Scopes
oauth2 oauth2Security payouts

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"
  }
}

POST /api/v1/payouts/{id}/actions/execute

Description

Execute a payout with status CREATED

Responses

HTTP Code Description Schema
200 Payout was executed PayoutResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
409 Unexpected state of payment transaction: “Illegal Workflow State” or “Transaction is Locked” ErrorResponse
422 Operation is declined ErrorResponse

Produces

  • application/json

Tags

  • payouts

Security

Type Name Scopes
oauth2 oauth2Security payouts

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"
  }
}

GET /api/v1/resultCodes

Description

Fetch complete list of result codes

Responses

HTTP Code Description Schema
200 OK Response 200

Response 200

Name Schema
resultCodes
optional
< ResultCodeInfo > array

Produces

  • application/json

Tags

  • info

POST /api/v1/transactions

Description

Creates new payment transaction

Body parameter

Request to create a new payment transaction

Name : body
Flags : required
Type : PaymentRequest

Responses

HTTP Code Description Schema
201 Payment created. PaymentResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
422 Operation is declined ErrorResponse

Consumes

  • application/json

Produces

  • application/json

Tags

  • payments

Security

Type Name Scopes
oauth2 oauth2Security transactions

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"
  }
}

GET /api/v1/transactions

Description

Fetch list of transactions

Responses

HTTP Code Description Schema
200 Data fetched Response 200
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Response 200

Name Schema
meta
optional
meta
transactions
optional
< TransactionListInfo > array

meta

Name Schema
hasNext
optional
boolean
hasPrev
optional
boolean
limit
optional
integer
offset
optional
integer

Produces

  • application/json

Tags

  • backoffice
  • payments

Security

Type Name Scopes
oauth2 oauth2Security transactions

Example HTTP response

Response 401

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

GET /api/v1/transactions/{id}

Description

Fetch data of transaction

Parameters

Type Name Description Schema
Path id
required
Transaction Id string

Responses

HTTP Code Description Schema
200 Transaction fetched TransactionDetails
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
404 Transaction not found ErrorResponse

Produces

  • application/json

Tags

  • backoffice
  • payments

Security

Type Name Scopes
oauth2 oauth2Security transactions

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"
}

POST /api/v1/transactions/{id}/actions/capture

Description

Capture authorized payment.

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

Parameters

Type Name Description Schema Default
Header Content-Length
optional
integer "0"
Path id
required
Id of authorized payment transaction to be captured string

Responses

HTTP Code Description Schema
200 Transaction captured TransactionStateResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
404 Transaction not found ErrorResponse
409 Unexpected state of payment transaction: “Illegal Workflow State” or “Transaction is Locked” ErrorResponse
422 Operation is declined ErrorResponse

Produces

  • application/json

Tags

  • backoffice
  • payments

Security

Type Name Scopes
oauth2 oauth2Security transactions

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"
  }
}

POST /api/v1/transactions/{id}/actions/payout

Description

Create Payout using card from payment transaction

Parameters

Type Name Description Schema
Path id
required
Id of payment transaction to get card details from string

Body parameter

Request to create payout for Purchase transaction

Name : body
Flags : required
Type : PayoutForPurchaseRequest

Responses

HTTP Code Description Schema
201 Payout created PayoutResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
404 Transaction not found ErrorResponse
409 Unexpected state of payment transaction: “Illegal Workflow State” or “Transaction is Locked” ErrorResponse
422 Operation is declined ErrorResponse

Consumes

  • application/json

Produces

  • application/json

Tags

  • payouts

Security

Type Name Scopes
oauth2 oauth2Security payouts

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"
  }
}

POST /api/v1/transactions/{id}/actions/refund

Description

Refund captured payment

Parameters

Type Name Description Schema
Path id
required
Id of captured payment transaction to be refunded string

Body parameter

Request for refund payment transaction

Name : body
Flags : required
Type : RefundRequest

Responses

HTTP Code Description Schema
201 Refund created RefundResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
404 Transaction not found ErrorResponse
409 Unexpected state of payment transaction: “Illegal Workflow State” or “Transaction is Locked” ErrorResponse
422 Operation is declined ErrorResponse

Consumes

  • application/json

Produces

  • application/json

Tags

  • backoffice
  • payments

Security

Type Name Scopes
oauth2 oauth2Security transactions

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"
  }
}

POST /api/v1/transactions/{id}/actions/void

Description

Void authorized payment

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

Parameters

Type Name Description Schema Default
Header Content-Length
optional
integer "0"
Path id
required
Id of authorized payment transaction to be voided string

Responses

HTTP Code Description Schema
200 Transaction voided TransactionStateResponse
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError
404 Transaction not found ErrorResponse
409 Unexpected state of payment transaction: “Illegal Workflow State” or “Transaction is Locked” ErrorResponse
422 Operation is declined ErrorResponse

Produces

  • application/json

Tags

  • backoffice
  • payments

Security

Type Name Scopes
oauth2 oauth2Security transactions

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"
  }
}

GET /api/v1/transactions/{id}/history

Description

Fetch transaction operations history

Parameters

Type Name Description Schema
Path id
required
Id of transaction string

Responses

HTTP Code Description Schema
200 Data fetched < TransactionHistoryItem > array
400 Invalid input ErrorResponse
401 Bearer token is missing or invalid
Headers :
WWW_Authenticate (string)
UnauthorizedError

Produces

  • application/json

Tags

  • backoffice
  • payments

Security

Type Name Scopes
oauth2 oauth2Security transactions

Example HTTP response

Response 401

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

Get Access Token

GET /auth/token

Description

Retrieve an access token for use with your API calls

Parameters

Type Name Description Schema Default
Query grant_type
required
Value must be set to client_credentials enum (client_credentials) "client_credentials"

Responses

HTTP Code Description Schema
200 The access token request is valid and authorized AccessTokenResponse
401 The request failed client authentication or is invalid Error

Produces

  • application/json

Tags

  • auth

Security

Type Name
basic basicSecurity

Definitions

AbstractResource

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

Name Description Schema
error
optional
When present, indicates that request has completed with error. Error
links
optional
If present, a links member can be used to represent links. The value of each links member is a “Links” object. < Link > array
meta
optional
When present, a meta member can be used to include non-standard meta-information. The value of each meta member is an object (a “meta object”).

Any members MAY be specified within meta objects.
object

AbstractTransaction

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

Name Description Schema
amount
required
Transaction amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number(decimal)
cardBrand
optional
CardBrand
cardExpiryMonth
optional
Expiry month as stated on the Card. (1-12)
Minimum value : 1
Maximum value : 12
Example : 5
integer
cardExpiryYear
optional
Expiry year as stated on the Card. 4 digits
Minimum value : 2018
Maximum value : 2050
Example : 2022
integer
cardToken
optional
Reference to the stored card data
Maximal length : 32
Example : "d7993562260c4ec2904612e5aa787261"
string
cardholder
optional
Cardholder name
Maximal length : 13
string
created
required
Transaction’s creation timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:43Z"
string(date-time)
cryptoAmount
optional
Transaction crypto amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number(decimal)
cryptoCurrency
optional
Currency
currency
required
Currency
customerAccountId
optional
Customer Account Id in external system (e.g. PayPal PayerID)
Maximal length : 64
string
customerBankId
optional
The bank id used by the terminal to handle the transaction
Maximal length : 64
string
customerEmail
optional
Customer Email
Maximal length : 512
string
description
optional
Description of the transaction shown to Customer
Maximal length : 512
string
executionId
optional
Transaction Id in external system (Processor Transaction ID)
Maximal length : 64
string
id
required
Unique transaction Id TransactionId
isMOTO
optional
Flag that indicates if the order was manually created in Merchant Portal boolean
maskedPan
optional
Masked PAN
Maximal length : 13
string
merchantCustomerId
optional
Id of the customer assigned by Merchant.
Maximal length : 128
string
paymentMethod
optional
Payment method PaymentMethod
processor
optional
Processor name of description
Maximal length : 128
string
state
required
TransactionState
type
required
TransactionType
updated
required
Transaction’s last update timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:51Z"
string(date-time)
verificationData
optional
The customer verification data map (key - value pairs): i.e. {‘firstName’:‘NO_MATCH’, ‘lastName’:‘MATCH’} object
verificationLevel
optional
The customer verification level i.e. 00, 01, 10, 11 or other string
Maximal length : 16
string

AccessTokenResponse

Name Description Schema
access_token
optional
The access token issued by PSP. The access token will expire (see expires_in), after which you’ll have to request a new access token.
Example : "f3ca90fc-f492-4ff3-872a-5f0b84a09445"
string
expires_in
optional
The lifetime in seconds of the access token
Example : 600
integer
scope
optional
Scopes expressed in the form of resource URL endpoints. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. string
token_type
optional
The type of the token issued as described in OAuth2.0 RFC6749, Section 7.1. Value is case insensitive. Always returns: “bearer
Example : "bearer"
enum (bearer)

ApiAccessMode

Type : enum (PAYMENT_PAGE, SERVER_TO_SERVER)

BillingAddress

The billing address is the address associated with payment card

Name Description Schema
city
required
City name
Maximal length : 80
string
countryCode
required
2-character IS0-3166-1 country code
Length : 2
Pattern : "[A-Z]{2}"
string
line1
required
Line 1 of the address (e.g., Number, street, etc)
Maximal length : 100
string
line2
optional
Line 2 of the address (e.g., Suite, apt #, etc)
Maximal length : 100
string
phone
optional
Phone number representing the customer. Required for some risk checks.
Maximal length : 25
string
postalCode
optional
Zip code or equivalent. Required in certain countries.
Maximal length : 30
string
state
optional
2-letter code for US states, and the equivalent for other countries
Maximal length : 50
string

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.

Name Description Schema
billingAddress
optional
BillingAddress
cardholder
required
Name of the cardholder as stated on Card
Maximal length : 128
Example : "Mr.Cardholder"
string
cvv
required
Credit card CVV from back side of the card. 3 digits
Length : 3
Example : "012"
string
expiryMonth
required
Expiry month as stated on the Card. (1-12)
Minimum value : 1
Maximum value : 12
Example : 5
integer
expiryYear
required
Expiry year as stated on the Card. 4 digits
Minimum value : 2017
Maximum value : 2050
Example : 2019
integer
pan
required
Primary Account Number
Pattern : "\\d+"
Example : "4000000000000002"
string

CardBrand

Card Brand

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

ChargebackState

Chargeback state of the PURCHASE transaction

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

Currency

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)

Customer

Name Description Schema
accountId
optional
The customer account Id in the external system. Required for some operations.
Maximal length : 64
Example : "1786162"
string
address1
optional
Maximal length : 100Example : "Red Street No 7" string
address2
optional
Maximal length : 100Example : "Tim Building, Apartment 1" string
bankAccountName
optional
The bank account name in the external system. Required for some operations.
Maximal length : 64
string
bankBranch
optional
The bank Branch in the external system. Required for some operations.
Maximal length : 64
string
bankId
optional
The bank Id in the external system. Required for some operations.
Maximal length : 64
Example : "CDERYDHH"
string
bankTransactionId
optional
The bank transaction Id in the external system. Required for some operations.
Maximal length : 64
Example : "CDERY123DHH"
string
channel
optional
A payment option in the external system. Required for some operations.
Maximal length : 64
Example : "CASH"
string
city
optional
Maximal length : 80Example : "Los Angeles" string
countryCode
optional
Length : 2Example : "US" string
dateOfBirth
optional
Example : "YYYY-MM-DD format: i.e. 1970-12-30" string(date)
email
required
Email address representing the customer
Maximal length : 127
Example : "andy@example.com"
string
firstName
optional
Maximal length : 50Example : "John" string
gender
optional
Biological gender at birth: male or female
Maximal length : 16
Example : "male"
string
ip
optional
Maximal length : 39Example : "216.3.128.12" string
lastName
optional
Maximal length : 50Example : "Snow" string
locale
optional
Preferred locale for the payment page in ISO 639-1 format. If not provided the en locale will be used. Locale
merchantCustomerId
optional
Id of the customer assigned by Merchant.
Maximal length : 128
Example : "cus-123456"
string
personalId
optional
The national/unique identification number. Required for some operations.
Maximal length : 64
string
phone
optional
Phone number representing the customer. Required for some risk checks.
Maximal length : 50
Example : "+22 607 123 4567"
string
phoneCountryCode
optional
Maximal length : 4Example : "0044 for UK" string
postCode
optional
Maximal length : 30Example : "90210" string
registrationDate
optional
The date when the customer was registered in the the external system (i.e. merchant system). Required for some operations.
Example : "YYYY-MM-DD format: i.e. 1970-12-30"
string(date)
securityCode
optional
Any security related code/password/otp. Required for some operations.
Maximal length : 64
string
state
optional
Maximal length : 50Example : "California" string
taxNumber
optional
Tax fiscal number of customer
Maximal length : 512
Example : "357123"
string
userAgent
optional
Maximal length : 512Example : "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" string

CustomerError

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

Name Description Schema
error
optional
Error message
Example : "Bad Request"
string
exception
optional
Java related exception message
Example : "org.springframework.http.converter.HttpMessageNotReadableException"
string
message
optional
Error message
Example : "Bad Request"
string
path
optional
Path used in the request
Example : "/api/v1/customers"
string
status
optional
HTTP Status Code
Example : 400
integer
timestamp
optional
Date and time when the operation reply was sent
Example : "2018-01-30T17:15:13.130+0000"
string

CustomerResponse

Polymorphism : Composition

Name Description Schema
customer
optional
Customer
error
optional
When present, indicates that request has completed with error. Error
links
optional
If present, a links member can be used to represent links. The value of each links member is a “Links” object. < Link > array
meta
optional
When present, a meta member can be used to include non-standard meta-information. The value of each meta member is an object (a “meta object”).

Any members MAY be specified within meta objects.
object

Error

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

Name Description Schema
code
required
The unique code that indicates the result status of the request. See the Result Codes for more detailed information.
Example : "06.40.000"
string
description
optional
Detailed description of the error string
fieldErrors
optional
Information about erroneous request fields, if any < FieldError > array
message
required
Error message
Example : "Transaction declined by bank"
string
status
required
HTTP Status Code integer

ErrorResponse

Polymorphism : Composition

Name Description Schema
error
optional
When present, indicates that request has completed with error. Error
links
optional
If present, a links member can be used to represent links. The value of each links member is a “Links” object. < Link > array
meta
optional
When present, a meta member can be used to include non-standard meta-information. The value of each meta member is an object (a “meta object”).

Any members MAY be specified within meta objects.
object

FieldError

Name Description Schema
field
required
Erroneous field path string
message
required
Field error message string

KYCAddress

KYC - defines properties of the customer’s address

Name Description Schema
addressLine1
optional
Field to contain address related data: street, number, flat etc
Example : "Wisdom street, No 7, Flat 3"
string
addressLine2
optional
Field to contain address related data: area, street, number, flat etc
Example : "Highland area"
string
city
optional
The city of the person’s address
Example : "Melbourne"
string
countryCode
required
The country of the person’s address
Example : "AU"
string
matchDetails
optional
MatchDetails
postalCode
optional
The postalCode of the person’s address
Example : "3000"
string
state
optional
The state of the person’s address
Example : "Victoria"
string

KYCCustomer

Name Description Schema
address
required
KYCAddress
dateOfBirth
optional
Example : "YYYY-MM-DD format: i.e. 1970-12-30" string(date)
email
optional
Email address representing the customer
Maximal length : 127
Example : "andy@example.com"
string
extSystemId1
optional
The customer Id in the external system
Maximal length : 64
Example : "CDER123YDHH"
string
extSystemId2
optional
The customer Id in the external system
Maximal length : 64
Example : "333777999"
string
firstName
optional
Maximal length : 50Example : "John" string
firstNames
optional
A list of all given names of the person < string > array
gender
optional
Email address representing the customer
Maximal length : 16
Example : "andy@example.com"
string
ip
optional
IP address of the customer
Maximal length : 127
Example : "101.101.101.101"
string
lastName
optional
Maximal length : 50Example : "Snow" string
matchDetails
optional
MatchDetails
merchantCustomerId
required
Id of the customer assigned by Merchant.
Maximal length : 128
Example : "cus-123456"
string
pepInfo
optional
A list of all PEP (politically exposed person) items < string > array
personalNumber
optional
The customer national id
Maximal length : 64
Example : "1786162112"
string
phone
optional
Phone number that belongs to the customer
Maximal length : 50
Example : "+22 607 123 4567"
string
phones
optional
KYCPhones
sanctionsInfo
optional
A list of all sanctions related to the person < string > array

KYCLoginRequest

KYC - defines properties of the Login request transaction.

Name Description Schema
customer
required
KYCCustomer
merchantTransactionId
required
Id of the transaction assigned by Merchant
Maximal length : 64
Example : "ORDER-123456"
string
providerCode
optional
KycProviderCode
returnUrl
required
The Merchant URL shown to the customer after a completed or declined identification
Example : "http://example.com/12345abcde/status"
string
webhookUrl
required
The Merchant webhook URL which will be called when the identification process is completed. Bigwallet will sent a KYCResponse object as payload
Example : "http://example.com/12345abcde/webhook"
string

KYCPhones

A list of phone numbers with the type.

Name Description Schema
phone
optional
The phone number
Example : "+300551133777"
string
type
optional
The phone type
Example : "MOBILE"
string

KYCRedirectResponse

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

Name Description Schema
id
optional
Id of the transaction assigned by Bigwallet
Example : "ORDER123"
string
merchantTransactionId
optional
Id of the transaction assigned by Merchant
Example : "ORDER-123456-M"
string
redirectUrl
optional
The Bigwallet redirect URL. The customer needs to be redirected to this URL to continue the identification process
Example : "http://example.com/ORDER123/redirect"
string

KYCRegisterChecksRequest

KYC Register Checks - defines properties of the request transaction.

Name Description Schema
customer
required
KYCCustomer
merchantTransactionId
required
Id of the transaction assigned by Merchant
Maximal length : 64
Example : "ORDER-123456"
string
providerCode
optional
KycProviderCode

KYCRegisterRequest

KYC - defines properties of the Registration request transaction.

Name Description Schema
customer
required
KYCCustomer
merchantTransactionId
required
Id of the transaction assigned by Merchant
Maximal length : 64
Example : "ORDER-123456"
string
providerCode
optional
KycProviderCode
returnUrl
required
The Merchant status URL shown to the customer after a completed or declined identification
Example : "http://example.com/12345abcde/status"
string
webhookUrl
required
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"
string

KYCResponse

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

Name Description Schema
customer
optional
KYCCustomer
customers
optional
A list of Customers < KYCCustomer > array
error
optional
Error message related to validations or other systems related errors
Example : "Country AU is not a supported"
string
id
optional
Id of the transaction assigned by Bigwallet
Example : "6d353a24d1d24b49bf69fc0cb4d25b8a"
string
identToken
optional
Token of the KYC operation created by an LOGIN/REGISTRATION request.
Example : "6556-ffrxzxxryzn0ovki08ca"
string
merchantTransactionId
optional
Id of the transaction assigned by Merchant
Example : "ORDER-123456-M"
string
resultCode
optional
ResultCode
transactionState
optional
KycTxState

KycProviderCode

KYC provider code

Type : enum (ENTERCASH, ZIGNSEC, NASPAY)

KycTxState

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
Name Schema
href
required
string
rel
required
enum (self, checkout, payment, void, capture, payment_ref, cancel, execute, approve, decline, refund, first, last, next, previous)

Locale

Locale in ISO 639-1 format

Type : string

MatchDetails

KYC - defines the match details

Name Description Schema
data
optional
A map of key-value pairs related to the KYC operation
Example : "{'Telecom1-LASTNAME':'Full match was made on Last Name/Surname', 'Postal-POSTALCODE':'Full match was made on Postal Code/Zip Code'}"
string
isMatch
optional
The field will show if KYC item was found
Example : true
boolean
level
optional
MatchLevel

MatchLevel

The match accuracy

Type : enum (LOW, MEDIUM, HIGH)

MerchantTerminalList

Name Schema
merchantTerminals
optional
< MerchantTerminalListItem > array

MerchantTerminalListItem

Name Description Schema
apiAccessMode
optional
ApiAccessMode
currencies
optional
< Currency > array
id
optional
integer
name
optional
string
paymentMethods
optional
An array of payment methods available to the merchant terminal < PaymentMethod > array
shopUrl
optional
Maximal length : 512 string

OperationState

OperationType is used in transaction history response

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

OperationType

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)

PaymentIntent#

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)

PaymentMethod#

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)

PaymentRequest#

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

Name Description Schema
amount
required
Transaction amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number
card
optional
Information about Credit Card. Required in Server-to-Server mode. Card
cardToken
optional
Reference to the stored card data
Maximal length : 32
Example : "d7993562260c4ec2904612e5aa787261"
string
currency
required
Currency
customer
optional
Information about the Customer. Required in Server-to-Server mode. Customer
description
required
Description of the transaction
Maximal length : 512
Example : "Purchase: 9 red roses"
string
intent
optional
Payment intent. If not provided then SALE will be used. PaymentIntent
merchantTransactionId
required
Id of the transaction assigned by Merchant
Maximal length : 100
Example : "ORDER-123456"
string
paymentMethod
optional
Payment method. If not provided then CREDIT_CARD will be used. PaymentMethod
shippingAddress
optional
ShippingAddress

PaymentResponse

Polymorphism : Composition

Name Description Schema
amount
optional
Transaction amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 13.1
number
created
required
Transaction’s creation timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:43Z"
string(date-time)
currency
optional
Currency
description
optional
Maximal length : 512 string
error
optional
When present, indicates that request has completed with error. Error
id
required
Transaction Id TransactionId
links
optional
If present, a links member can be used to represent links. The value of each links member is a “Links” object. < Link > array
merchantTransactionId
optional
Id of the transaction assigned by Merchant
Maximal length : 100
Example : "ORDER-123456"
string
meta
optional
When present, a meta member can be used to include non-standard meta-information. The value of each meta member is an object (a “meta object”).

Any members MAY be specified within meta objects.
object
shippingAddress
optional
ShippingAddress
state
required
TransactionState
updated
required
Transaction’s last update timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:51Z"
string(date-time)

PayoutForPurchaseRequest

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

Name Description Schema
amount
required
Amount of payout
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number
customer
optional
Information about the Customer. Specify only those fields that need to be updated, all other data will be taken from Purchase transaction. Customer
description
required
Description of the payout
Maximal length : 512
string
merchantTransactionId
optional
Id of the transaction assigned by Merchant
Maximal length : 100
Example : "PAYOUT-123456"
string

PayoutIntent#

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)

PayoutRequest

A request to create new payout.

Name Description Schema
amount
required
Amount of payout
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number
card
optional
Information about Credit Card. Required in Server-to-Server mode. Card
currency
required
Currency
customer
optional
Information about the Customer. Required in Server-to-Server mode. Customer
description
required
Description of the payout
Maximal length : 512
string
intent
optional
Payout Intent. If not provided then EXECUTE will be used. PayoutIntent
merchantTransactionId
required
Id of the transaction assigned by Merchant
Maximal length : 100
Example : "PAYOUT-123456"
string
paymentMethod
optional
Payment method. If not provided then CREDIT_CARD will be used. PaymentMethod

PayoutResponse

Polymorphism : Composition

Name Description Schema
amount
optional
Amount of payout
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 13.1
number
created
required
Transaction’s creation timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:43Z"
string(date-time)
currency
optional
Currency of payout Currency
description
optional
Optional description of the payout
Maximal length : 512
Example : "Withdrawal to customer ID123456"
string
error
optional
When present, indicates that request has completed with error. Error
id
required
Transaction Id TransactionId
links
optional
If present, a links member can be used to represent links. The value of each links member is a “Links” object. < Link > array
merchantTransactionId
optional
Id of the transaction assigned by Merchant
Maximal length : 100
Example : "ORDER-123456"
string
meta
optional
When present, a meta member can be used to include non-standard meta-information. The value of each meta member is an object (a “meta object”).

Any members MAY be specified within meta objects.
object
state
required
The state of payout transaction TransactionState
updated
required
Transaction’s last update timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:51Z"
string(date-time)

PayoutTransaction#

Defines properties of the PAYOUT transaction.

Polymorphism : Inheritance
Discriminator : type

Name Description Schema
amount
required
Transaction amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number(decimal)
cardBrand
optional
CardBrand
cardExpiryMonth
optional
Expiry month as stated on the Card. (1-12)
Minimum value : 1
Maximum value : 12
Example : 5
integer
cardExpiryYear
optional
Expiry year as stated on the Card. 4 digits
Minimum value : 2018
Maximum value : 2050
Example : 2022
integer
cardToken
optional
Reference to the stored card data
Maximal length : 32
Example : "d7993562260c4ec2904612e5aa787261"
string
cardholder
optional
Cardholder name
Maximal length : 13
string
created
required
Transaction’s creation timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:43Z"
string(date-time)
cryptoAmount
optional
Transaction crypto amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number(decimal)
cryptoCurrency
optional
Currency
currency
required
Currency
customerAccountId
optional
Customer Account Id in external system (e.g. PayPal PayerID)
Maximal length : 64
string
customerBankId
optional
The bank id used by the terminal to handle the transaction
Maximal length : 64
string
customerEmail
optional
Customer Email
Maximal length : 512
string
description
optional
Description of the transaction shown to Customer
Maximal length : 512
string
executionId
optional
Transaction Id in external system (Processor Transaction ID)
Maximal length : 64
string
id
required
Unique transaction Id TransactionId
isMOTO
optional
Flag that indicates if the order was manually created in Merchant Portal boolean
maskedPan
optional
Masked PAN
Maximal length : 13
string
merchantCustomerId
optional
Id of the customer assigned by Merchant.
Maximal length : 128
string
merchantTransactionId
optional
Id of the transaction assigned by Merchant
Maximal length : 100
Example : "PAYOUT-123456"
string
paymentMethod
optional
Payment method PaymentMethod
processor
optional
Processor name of description
Maximal length : 128
string
state
required
TransactionState
type
required
TransactionType
updated
required
Transaction’s last update timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:51Z"
string(date-time)
verificationData
optional
The customer verification data map (key - value pairs): i.e. {‘firstName’:‘NO_MATCH’, ‘lastName’:‘MATCH’} object
verificationLevel
optional
The customer verification level i.e. 00, 01, 10, 11 or other string
Maximal length : 16
string

PurchaseTransaction

Defines properties of the PURCHASE transaction.

Polymorphism : Inheritance
Discriminator : type

Name Description Schema
amount
required
Transaction amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number(decimal)
cardBrand
optional
CardBrand
cardExpiryMonth
optional
Expiry month as stated on the Card. (1-12)
Minimum value : 1
Maximum value : 12
Example : 5
integer
cardExpiryYear
optional
Expiry year as stated on the Card. 4 digits
Minimum value : 2018
Maximum value : 2050
Example : 2022
integer
cardToken
optional
Reference to the stored card data
Maximal length : 32
Example : "d7993562260c4ec2904612e5aa787261"
string
cardholder
optional
Cardholder name
Maximal length : 13
string
chargebackState
optional
ChargebackState
created
required
Transaction’s creation timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:43Z"
string(date-time)
cryptoAmount
optional
Transaction crypto amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number(decimal)
cryptoCurrency
optional
Currency
currency
required
Currency
customerAccountId
optional
Customer Account Id in external system (e.g. PayPal PayerID)
Maximal length : 64
string
customerBankId
optional
The bank id used by the terminal to handle the transaction
Maximal length : 64
string
customerEmail
optional
Customer Email
Maximal length : 512
string
description
optional
Description of the transaction shown to Customer
Maximal length : 512
string
executionId
optional
Transaction Id in external system (Processor Transaction ID)
Maximal length : 64
string
id
required
Unique transaction Id TransactionId
isMOTO
optional
Flag that indicates if the order was manually created in Merchant Portal boolean
maskedPan
optional
Masked PAN
Maximal length : 13
string
merchantCustomerId
optional
Id of the customer assigned by Merchant.
Maximal length : 128
string
merchantTransactionId
required
Id of the transaction assigned by Merchant
Maximal length : 100
Example : "ORDER-123456"
string
paymentMethod
optional
Payment method PaymentMethod
processor
optional
Processor name of description
Maximal length : 128
string
refundedAmount
optional
Amount refunded. Can’t be greater than transaction amount. Value may not be present, when it is zero.
Minimum value : 1.0E-18
Maximum value : 999999.99
number(decimal)
state
required
TransactionState
type
required
TransactionType
updated
required
Transaction’s last update timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:51Z"
string(date-time)
verificationData
optional
The customer verification data map (key - value pairs): i.e. {‘firstName’:‘NO_MATCH’, ‘lastName’:‘MATCH’} object
verificationLevel
optional
The customer verification level i.e. 00, 01, 10, 11 or other string
Maximal length : 16
string

RefundRequest

Name Description Schema
amount
required
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-18
Maximum value : 999999.99
number
description
optional
Maximal length : 512 string

RefundResponse

Polymorphism : Composition

Name Description Schema
amount
optional
Refund amount in the same currency as original payment.
Can not be greater than initial transaction amount minus already refunded amount.
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 12.98
number
created
optional
Transaction’s creation timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:42Z"
string(date-time)
description
optional
Description (comment) of the refund request
Maximal length : 512
Example : "Refunded due to service was not provided"
string
error
optional
When present, indicates that request has completed with error. Error
id
optional
Transaction Id TransactionId
links
optional
If present, a links member can be used to represent links. The value of each links member is a “Links” object. < Link > array
meta
optional
When present, a meta member can be used to include non-standard meta-information. The value of each meta member is an object (a “meta object”).

Any members MAY be specified within meta objects.
object
paymentTransactionId
optional
Id of payment transaction string
state
optional
TransactionState
updated
optional
Transaction’s last update timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:51Z"
string(date-time)

RefundTransaction

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

Name Description Schema
amount
required
Transaction amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number(decimal)
cardBrand
optional
CardBrand
cardExpiryMonth
optional
Expiry month as stated on the Card. (1-12)
Minimum value : 1
Maximum value : 12
Example : 5
integer
cardExpiryYear
optional
Expiry year as stated on the Card. 4 digits
Minimum value : 2018
Maximum value : 2050
Example : 2022
integer
cardToken
optional
Reference to the stored card data
Maximal length : 32
Example : "d7993562260c4ec2904612e5aa787261"
string
cardholder
optional
Cardholder name
Maximal length : 13
string
created
required
Transaction’s creation timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:43Z"
string(date-time)
cryptoAmount
optional
Transaction crypto amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 19.98
number(decimal)
cryptoCurrency
optional
Currency
currency
required
Currency
customerAccountId
optional
Customer Account Id in external system (e.g. PayPal PayerID)
Maximal length : 64
string
customerBankId
optional
The bank id used by the terminal to handle the transaction
Maximal length : 64
string
customerEmail
optional
Customer Email
Maximal length : 512
string
description
optional
Description of the transaction shown to Customer
Maximal length : 512
string
executionId
optional
Transaction Id in external system (Processor Transaction ID)
Maximal length : 64
string
id
required
Unique transaction Id TransactionId
isMOTO
optional
Flag that indicates if the order was manually created in Merchant Portal boolean
maskedPan
optional
Masked PAN
Maximal length : 13
string
merchantCustomerId
optional
Id of the customer assigned by Merchant.
Maximal length : 128
string
paymentMethod
optional
Payment method PaymentMethod
paymentTransactionId
required
ID of the Purchase transaction TransactionId
processor
optional
Processor name of description
Maximal length : 128
string
state
required
TransactionState
type
required
TransactionType
updated
required
Transaction’s last update timestamp as defined by full-date in RFC3339
Example : "2017-01-10T09:37:51Z"
string(date-time)
verificationData
optional
The customer verification data map (key - value pairs): i.e. {‘firstName’:‘NO_MATCH’, ‘lastName’:‘MATCH’} object
verificationLevel
optional
The customer verification level i.e. 00, 01, 10, 11 or other string
Maximal length : 16
string

ResultCode

Result code. See https://bigwallet.com/docs/result-codes

Type : string

ResultCodeInfo

Name Description Schema
code
required
Result code has format dd.dd.ddd, i.e. 3 groups of digits. See Result Codes section for details.
Length : 9
Pattern : "[0-9]{2}\\.[0-9]{2}\\.[0-9]{3}"
Example : "01.23.456"
string
description
required
ResultCode’s description string

ShippingAddress

The shipping address is where customer wants order delivered. This can be the same as the billing address, or it can be different.

Name Description Schema
city
required
City name
Maximal length : 80
string
countryCode
required
2-character IS0-3166-1 country code
Length : 2
Pattern : "[A-Z]{2}"
string
line1
required
Line 1 of the address (e.g., Number, street, etc)
Maximal length : 100
string
line2
optional
Line 2 of the address (e.g., Suite, apt #, etc)
Maximal length : 100
string
phone
optional
Phone number representing the customer. Required for some risk checks.
Maximal length : 50
string
postalCode
optional
Zip code or equivalent. Required in certain countries.
Maximal length : 30
string
recipientName
required
Intended recipients name
Maximal length : 100
string
state
optional
2-letter code for US states, and the equivalent for other countries
Maximal length : 50
string

TransactionChangedEvent

Name Description Schema
created
required
Event’s creation timestamp. As defined by full-date in RFC3339 string(date-time)
error
optional
Error field is present when operation has not completed successfully ResultCodeInfo
operationState
required
OperationState
operationType
required
OperationType
transaction
required
AbstractTransaction
type
required
enum (TransactionChangedEvent)

TransactionDetails

Name Description Schema
amount
required
Transaction amount
Minimum value : 1.0E-18
Maximum value : 999999.99
number
chargebackState
optional
Chargeback State ChargebackState
created
optional
read-only
Date and time when transaction was created string
currency
required
Currency
customer
optional
Information about Customer Customer
description
required
Maximal length : 512 string
id
optional
Unique transaction Id TransactionId
links
required
< Link > array
merchantTransactionId
optional
Id of the transaction assigned by Merchant
Maximal length : 128
string
paymentMethod
optional
Payment method PaymentMethod
refundedAmount
optional
Amount refunded. Applicable only for payment transactions. Can’t be greater than transaction amount.
Minimum value : 1.0E-18
Maximum value : 999999.99
number
resultCode
optional
ResultCode
shippingAddress
optional
ShippingAddress
state
optional
Transaction State TransactionState
type
optional
Transaction type TransactionType
updated
optional
read-only
Date and time when transaction was last updated string

TransactionHistoryItem

Name Schema
details
optional
string
operation
optional
OperationType
operationState
optional
OperationState
resultCode
optional
ResultCode
timestamp
optional
string
transactionState
optional
TransactionState

TransactionId

Transaction ID

Type : string

TransactionListInfo

Name Description Schema
amount
required
Transaction amount
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 123.45
number
arn
optional
Acquirer’s Reference Number string
cardBrand
optional
Card brand string
cardNumber
optional
Masked card number
Example : "400000...0002"
string
cardholder
optional
Cardholder name
Example : "Mr. Cardholder"
string
chargebackState
optional
ChargebackState
created
required
Date and time when transaction was created
Example : "2017-01-11T08:49:36.524Z"
string
cryptoCurrency
optional
Currency
currency
optional
Currency
email
optional
Customer’s email
Example : "andy@example.com"
string
id
required
Unique transaction Id TransactionId
ip
optional
Customer’s IP address
Example : "216.3.128.12"
string
merchantTransactionId
optional
Id of the transaction assigned by Merchant
Example : "ORDER-1234"
string
orderDescription
optional
Order description
Example : "Purchase 9 red roses"
string
refundedAmount
optional
Amount refunded. Applicable only for payment transactions. Can’t be greater than transaction amount.
Minimum value : 1.0E-18
Maximum value : 999999.99
Example : 12.34
number
resultCode
optional
ResultCode
state
required
TransactionState
type
required
TransactionType
updated
required
Date and time when transaction was last updated
Example : "2017-01-11T08:49:36.523Z"
string

TransactionState

Transaction State

  • ERROR – Transaction processing was not started due to error
  • CREATED – The transaction was just created
  • PENDING – Payment page was shown to Customer
  • IN_PROGRESS – Card details filled, transaction initiated
  • AUTHORIZED – Transaction was authorized by bank
  • ON_HOLD – Transaction was authorized but processing was stopped due to high risk. The transaction should be captured explicitly.
  • COMPLETED – Transaction processing was completed successfully.
  • REFUNDED – Transaction was fully refunded
  • PARTIALLY_REFUNDED – Transaction was refunded partially
  • DECLINED –Transaction was declined
  • VOIDED – Transaction was voided
  • CANCELLED – Transaction was cancelled by the Customer, e.g. by clicking the “Cancel” button on payment page.
  • TIMEOUT – Customer didn’t competed transaction flow, e.g. didn’t return from 3D-Secure check.

Type : enum (ERROR, CREATED, PENDING, IN_PROGRESS, AUTHORIZED, ON_HOLD, COMPLETED, REFUNDED, PARTIALLY_REFUNDED, DECLINED, VOIDED, CANCELLED, TIMEOUT)

TransactionStateResponse

Name Description Schema
created
required
Transaction’s creation timestamp. As defined by full-date in RFC3339 string(date-time)
error
optional
Error field is present when operation has not completed successfully Error
id
required
Transaction Id TransactionId
links
optional
< Link > array
state
required
TransactionState
updated
required
Transaction’s last update timestamp. As defined by full-date in RFC3339 string(date-time)

TransactionType

Transaction Type

Type : enum (PURCHASE, REFUND, PAYOUT)

UnauthorizedError

Name Description Schema
error
required
Example : "invalid_token" string
error_description
required
Example : "Access token is not found" string

Result Codes


Result codes explains

Here you can see a list of result codes which can be obtained in the code field of Error object.

Note

The response codes are a subject of change.

Structure of result codes

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

Codes Error Source
00.xx.xxx Operation successful
01.xx.xxx Customer
04.xx.xxx KYC provider
05.xx.xxx 3D-Secure
06.xx.xxx Bank-Acquirer
07.xx.xxx Bank-Issuer
09.xx.xxx System errors

Second group defines the category of the error:

Error Categories

Codes Error Category
xx.00.xxx General category
xx.10.xxx Request validation
xx.20.xxx Checkout page
xx.30.xxx Payer
xx.40.xxx Payee
xx.50.xxx Antifraud
xx.55.xxx Blacklists
xx.60.xxx Business rules
xx.65.xxx Card Data
xx.80.xxx Communication issues
xx.90.xxx Malfunction

The last group defines the exact reason of the error.

Some reasons are listed below:

Error Reasons

Codes Error Reason
xx.xx.000 General reason
xx.xx.008 Cancel
xx.xx.102 Processing
xx.xx.404 Resource not found
xx.xx.403 Operation forbidden
xx.xx.400 Bad request
xx.xx.405 Method not allowed
xx.xx.408 Processing timeout
xx.xx.422 General decline
xx.xx.502 Routing ruleset not found
xx.xx.406 Unaccepted parameter
xx.xx.019 Card scheme
xx.xx.007 Limits
xx.xx.018 Country
xx.xx.409 Illegal workflow state
xx.xx.417 Not fully 3dsecure
xx.xx.418 Insufficient funds

Example: 02.10.001 (Cancelled by Customer) means:

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

Complete list of result codes

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

©2016-2019 bigwallet.com