Merchant API (2020-07-03)

Download OpenAPI specification:Download

bigwpay Support Team: support@app.bigwpay.com URL: https://support.app.bigwpay.com License: Apache 2.0 Terms of Service

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

Complete documentation describing how to use this API

Authentication

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

Security Scheme Type	HTTP
HTTP Authorization Scheme	basic

oauth2Security

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

Security Scheme Type	OAuth2
clientCredentials OAuth Flow	Token URL: https://app.bigwpay.com/auth/token Scopes: `transactions` - Operations with transactions `payouts` - Payouts `kyc` - Customers registration and identification `customerProfiles` - Customers profiles management `cards` - Card verify

Access Token

OAuth 2.0 Server API

Get Access Token

Retrieve an access token for use with your API calls

Authorizations:

basicSecurity

query Parameters

grant_type

required

string

Default: "client_credentials"

Value: "client_credentials"

Value must be set to client_credentials

Responses

200

The access token request is valid and authorized

401

The request failed client authentication or is invalid

get/auth/token

Test server

https://app.bigwallet.online/auth/token

Production server

https://app.bigwpay.com/auth/token

Response samples

Content type

application/json

Copy

Expand all Collapse all


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

Payments

Merchant Payments API

listTransactions

Fetch list of transactions

Authorizations:

oauth2Security (transactions)

Responses

200

Data fetched

401

Bearer token is missing or invalid

get/api/v1/transactions

Test server

https://app.bigwallet.online/api/v1/transactions

Production server

https://app.bigwpay.com/api/v1/transactions

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"transactions": 
[
{"id": "d7993562260c4ec2904612e5aa787261",
"type": "PURCHASE",
"created": "2017-01-11T08:49:36.524Z",
"updated": "2017-01-11T08:49:36.523Z",
"state": "ERROR",
"amount": 123.45,
"refundedAmount": 12.34,
"currency": "USD",
"cryptoCurrency": "USD",
"merchantTransactionId": "ORDER-1234",
"arn": "string",
"cardholder": "Mr. Cardholder",
"cardNumber": "400000...0002",
"email": "andy@example.com",
"ip": "216.3.128.12",
"cardBrand": "string",
"orderDescription": "Purchase 9 red roses",
"resultCode": 
{"code": "00.00.000",
"description": "OK"
},
"chargebackState": "CLAIM"
}
],
"meta": 
{"offset": 0,
"limit": 0,
"hasPrev": true,
"hasNext": true
}
}

createTransaction

Creates new payment transaction

Authorizations:

oauth2Security (transactions)

Request Body schema: application/json

Request to create a new payment transaction

intent	string (PaymentIntent) Enum: "AUTHORIZE" "SALE" 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.
paymentMethod	string (PaymentMethod) 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" "NETPAY" "TRONIPAY" "TRONIPAY_CRYPTO" "IACCOUNT" "PAYBOUTIQUE" "YANDEX_MONEY" "QIWI" "EPG" "DRAGONPHOENIX" "AWEPAY" "PAYTECHNO_CRYPTO" "MPESA" "PAYTRUST88" "XENTUM" "ASTROPAY_CARD" "OROUNDA" "LEOGAMING" "PAPARA" "BESTPAYCARD_CRYPTO" "MIR" "TELE_2" "MTS" "MEGAFON" "BEELINE" "ALOGATEWAY" "WEBMONEY" "WEBMONEY_LIGHT" "CASHU" "PAYEER" "PERFECT_MONEY" "ALFA_CLICK" "ALIPAY" "WELLCOINPAY" "NEOSURF" "SETTLEME" "APPLE_PAY" "MALDOPAY" "XPATE" "ANINDA" "FOURBILL" "WAYFORPAY" "DUSPAY" "ENFINS" "CRYPTO" "IPAYTOTAL" "UPHOLD" "DIRECTA24" "BCASHY" "ADVCASH" "ESKAYPAY" "GPAY" "INSTADEBIT" "IDEBIT" "CRYPTOMARINE" "PAYMEGA" "TRANSACTWORLD" "FOXAPAY" "DRAGONPAY" "PLASMAPAY" "FREEKASSA" "ISIGNTHIS" "UNNAX" "PIASTRIX" "MOBILEPAY" "BONYPAY" "CERTUS" "WHITEPAID" Payment method. Select between various methods of payment – `CREDIT_CARD` is chosen by default.
amount required	number multiple of 1e-18 [ 1e-18 .. 999999.99 ] Transaction amount
currency required	string <ISO 4217> (Currency) Enum: "CNY" "EUR" "GBP" "RUB" "USD" "XBT" "B2BX" "BCH" "DOGE" "XTH" "USDT" "ADA" "LTC" "XLM" "XRP" "EOS" "BAT" "XMR" ISO 4217 currency code, crypto currency code (XBT is used for BTC, XTH is used for ETH to avoid conflict with fiat currency)
merchantTransactionId required	string <= 100 characters Id of the transaction assigned by Merchant
description required	string <= 512 characters Description of the transaction
shippingAddress	object (ShippingAddress) The shipping address is where customer wants order delivered. This can be the same as the billing address, or it can be different.
customer	object (Customer)
card	object (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.
cardToken	string <= 32 characters Reference to the stored card data
startRecurring	boolean Flag to trigger the start of a recurring transaction. A recurring token will be generated and sent back to merchant
recurringToken	string <= 32 characters Multi-use reference token to be used for recurring operations
cashierPaymentMethod	string <= 32 characters Cashier Payment method
returnUrl	string <= 256 characters URL to redirect Customer after processing. Overrides terminal-level settings

Responses

201

Payment created.

400

Invalid input

401

Bearer token is missing or invalid

422

Operation is declined

post/api/v1/transactions

Test server

https://app.bigwallet.online/api/v1/transactions

Production server

https://app.bigwpay.com/api/v1/transactions

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all


{"intent": "SALE",
"paymentMethod": "CREDIT_CARD",
"amount": 19.98,
"currency": "USD",
"merchantTransactionId": "ORDER-123456",
"description": "Purchase: 9 red roses",
"shippingAddress": 
{"line1": "7, Sunny street",
"line2": "Office 3",
"city": "Mountain View",
"countryCode": "US",
"postalCode": 90210,
"state": "CA",
"phoneCountryCode": 408,
"phone": "606-5775",
"recipientName": "John Smith"
},
"customer": 
{"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"
},
"card": 
{"cardholder": "Mr.Cardholder",
"pan": "4000000000000002",
"expiryMonth": 5,
"expiryYear": 2019,
"cvv": "012",
"billingAddress": 
{"line1": "7, Sunny street",
"line2": "Office 3",
"city": "Mountain View",
"countryCode": "US",
"postalCode": 90210,
"state": "CA",
"phoneCountryCode": 408,
"phone": "606-5775"
}
},
"cardToken": "d7993562260c4ec2904612e5aa787261",
"startRecurring": true,
"recurringToken": "2bfe72bccdf44e16a044b8266389b05f",
"cashierPaymentMethod": "CASHIER_123",
"returnUrl": "https://myshop.com/status"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": "d7993562260c4ec2904612e5aa787261",
"created": "2017-01-10T09:37:43.000Z",
"updated": "2017-01-10T09:37:51.000Z",
"state": "ERROR",
"amount": 13.1,
"currency": "USD",
"merchantTransactionId": "ORDER-123456",
"description": "string",
"shippingAddress": 
{"line1": "7, Sunny street",
"line2": "Office 3",
"city": "Mountain View",
"countryCode": "US",
"postalCode": 90210,
"state": "CA",
"phoneCountryCode": 408,
"phone": "606-5775",
"recipientName": "John Smith"
},
"links": 
[
{"href": "https://app.bigwpay.com/api/v1/transactions/9771fe8e1b4a4ce5b5f51c8681b58985",
"rel": "self"
}
],
"meta": { },
"error": 
{"status": 0,
"code": "06.40.000",
"message": "Transaction declined by bank",
"description": "string",
"fieldErrors": 
[
{"field": "amount",
"message": "Must be positive"
}
]
}
}

getTransaction

Fetch data of transaction

Authorizations:

oauth2Security (transactions)

path Parameters

required

string /[a-zA-Z0-9]{32}/

Transaction Id

Responses

200

Transaction fetched

400

Invalid input

401

Bearer token is missing or invalid

404

Transaction not found

get/api/v1/transactions/{id}

Test server

https://app.bigwallet.online/api/v1/transactions/{id}

Production server

https://app.bigwpay.com/api/v1/transactions/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"id": "d7993562260c4ec2904612e5aa787261",
"type": "PURCHASE",
"paymentMethod": "CREDIT_CARD",
"state": "ERROR",
"chargebackState": "CLAIM",
"created": "string",
"updated": "string",
"customer": 
{"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"
},
"amount": 1e-18,
"currency": "USD",
"refundedAmount": 1e-18,
"merchantTransactionId": "string",
"description": "string",
"shippingAddress": 
{"line1": "7, Sunny street",
"line2": "Office 3",
"city": "Mountain View",
"countryCode": "US",
"postalCode": 90210,
"state": "CA",
"phoneCountryCode": 408,
"phone": "606-5775",
"recipientName": "John Smith"
},
"resultCode": 
{"code":