API docs by Redocly

bbpay.one API (1.0.46)

Download OpenAPI specification:

License: Apache-2.0

Gateway API

Payments

Payments API

Payment processing completed Webhook

Publish details of a new processed payment.

Authorizations:
SignatureAuth
Request Body schema: application/json

Information about a new finalized payment

id
string <= 32 characters

Payment Id

referenceId
string <= 256 characters

referenceId from payment request

created
string <ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS)>

Date and time when this payment was created, in UTC time zone

paymentType
string (PaymentType)
Enum: "DEPOSIT" "WITHDRAWAL" "REFUND"

Payment Type

state
string (PaymentState)
Enum: "CHECKOUT" "PENDING" "AUTHORIZED" "CANCELLED" "DECLINED" "COMPLETED"

Payment State

description
string <= 512 characters

Description of the transaction

parentPaymentId
string <= 32 characters

Initial transaction Id from payment request

paymentMethod
string (PaymentMethod)
Enum: "BASIC_CARD" "CRYPTO" "FLEXEPIN" "MACROPAY" "SKRILL" "PAYRETAILERS" "LOCALPAYMENT" "MONNET" "PAYPAL" "NETELLER" "TRUSTPAYMENTS" "PAYMAXIS" "GATE8TRANSACT" "TINK" "B2BINPAY" "CLICK" "MONETIX" "PERFECTMONEY" "VOLT" "KESSPAY" "BILLLINE" "NGENIUS" "ASTROPAY" "ALYCEPAY" "PIX" "BOLETO" "UPI" "PAYTM" "NETBANKING" "FINRAX" "SPOYNT" "XINPAY" "OMNIMATRIX" "DPOPAY" "EXTERNAL_HPP" "XANPAY" "INRPAY" "ARI10" "SOFORT" "GIROPAY" "PAYSAFECARD" "PAYSAFECASH" "OPEN_BANKING" "KLARNA" "SPEI" "PAYCASH" "RAPIPAGO" "PAGOFACIL" "RAPIDTRANSFER" "MOBILE_MONEY" "INTERAC" "INTERAC_ETO" "INTERAC_RTO" "INTERAC_ACH" "PICPAY" "MOLLIE" "TED" "ZIPAY" "PSE" "EFECTY" "BANKTRANSFER" "BANKTRANSFER_AR" "BANKTRANSFER_CL" "BANKTRANSFER_CO" "BANKTRANSFER_MX" "BANKTRANSFER_PE" "BANKTRANSFER_TR" "PEC" "OXXO" "WEBPAY" "PAGOEFECTIVO" "MIFINITY" "PAYPORT" "JETONCASH" "JETONWALLET" "NEOSURF" "NODA" "NODA_REVOLUT" "ALFAKIT" "PAYFUN" "EMANAT" "M10" "RUBPAY" "MONERCHY" "MUCHBETTER" "YAPILY" "INAI" "IMPS" "RTGS" "PAYID" "ZOTAPAY" "SBP" "SBP_CROSS_BORDER" "P2P_CARD" "P2P_IBAN" "P2P_SBP" "P2P_MOBILE" "P2P_M10" "P2P_EMANAT" "P2P_KAPITAL" "P2P_ACCESS" "P2P_CROSS_BORDER" "PUSH" "GATEIQ" "VIETTEL" "ZALO" "QR" "CUP" "CODI" "PAY2PLAY" "BKASH" "NAGAD" "ROCKET" "VIRTUAL_ACCOUNT" "MULTIBANCO" "BLIK" "MBWAY" "P24" "MISTERCASH" "MACH" "KHIPU" "NEFT" "STICPAY" "SBERPAY" "MOBILE_COMMERCE" "BINANCE_PAY" "MPAY" "CHEK" "KLAP_EFECTIVO" "KLAP_TRANSFERENCIA" "PAGO46" "HITES" "SERVIFACIL" "OPENPAYD" "FAWRY" "EPS" "IDEAL" "TRUSTLY" "USSD" "MPESA" "ENAIRA" "ONEVOUCHER" "BANCONTACT" "SWISH" "EFT" "GCASH" "PAYMAYA" "PAGO_MOVIL" "PAGO_MOVIL_INST" "BIOPAGO" "CASH" "VOUCHERRY" "SOFT2PAY" "APPLEPAY" "GOOGLEPAY" "BRITE" "VOUCHSTAR" "REVOLUT" "ONLINE_BANKING" "PROMPTPAY" "TRUEMONEY" "MOMOPAY_VN" "MOMOPAY_RW" "VNPAY_QR" "N26" "WISE" "PAYDO_WALLET" "PAPARA" "PAYPAY" "PARAZULA" "PAYFIX" "PHONEPE" "CIP" "BASIC_CARD_HPP" "WAVE" "PIASTRIX" "DANA" "SHOPEEPAY" "QRIS" "OVO" "ALFAMART" "GOPAY" "CASHLIB" "YAPE" "PAYNOW" "MERCADOPAGO" "DRAGON_PAY" "FPX" "HAVALE" "MEFETE" "POPY" "NEQUI" "JAZZCASH" "EASYPAISA" "TRANSFIYA" "KBZ" "BYBIT_PAY" "HELP2PAY" "SEPA" "FPS" "PAYOUT_SEPA_BATCH" "PAYOUT_NONSEPA_REQUEST"

Payment Method

object (PaymentMethodDetails)
amount
number multiple of 1e-18 [ 0.00001 .. 1000000000 ]

Amount sent to the payment provider

currency
string <ISO 4217 code for FIAT currencies or cryptocurrency symbol>

Currency sent to the payment provider

customerAmount
number

Amount from payment request. Filled only if the request currency differs from the currency sent to the payment provider.

customerCurrency
string <ISO 4217 code for FIAT currencies or cryptocurrency symbol>

Currency from payment request. Filled only if it differs from the currency sent to the payment provider.

redirectUrl
string <= 256 characters

URL to redirect the customer

errorCode
string

Check 'Error Codes' section for details

errorMessage
string

Check 'Error Codes' section for details

externalResultCode
string

Result code from external provider

object (Customer)
object (BillingAddress)

Customer's billing address

startRecurring
boolean

Indicates whether this payment has started a recurring chain

preAuth
boolean

Indicates whether this is a Pre-Authorization request (for 2-phase deposit)

recurringToken
string

Token that can be used to continue the recurring chain

terminalName
string

The name of the provider that was used to process this payment

externalFeeAmount
number

Provider fee. Filled only if supported by the provider.

externalFeeCurrency
string <ISO 4217 code for FIAT currencies or cryptocurrency symbol>

Provider fee currency. Filled only if supported by the provider.

Responses

Request samples

Content type
application/json
{
  • "id": "91d27876e87f4b22b3ecd53924bf973d",
  • "referenceId": "payment-123",
  • "created": "2030-12-25T10:11:12",
  • "paymentType": "DEPOSIT",
  • "state": "PENDING",
  • "description": "Deposit via TEST shop",
  • "parentPaymentId": "91d27876e87f4b22b3ecd53924bf973d",
  • "paymentMethod": "BASIC_CARD",
  • "paymentMethodDetails": {
    },
  • "amount": 11.12,
  • "currency": "EUR",
  • "customerAmount": 15,
  • "customerCurrency": "USD",
  • "redirectUrl": "http://start/payment/6ccaa03cb2c242a68ce332f38fedfad7",
  • "errorCode": "4.01",
  • "errorMessage": "Insufficient Funds",
  • "externalResultCode": "03",
  • "customer": {
    },
  • "billingAddress": {
    },
  • "startRecurring": true,
  • "preAuth": true,
  • "recurringToken": "string",
  • "terminalName": "string",
  • "externalFeeAmount": 15,
  • "externalFeeCurrency": "USD"
}

Get payments

Get a list of payments sorted by creation date (most recent first)

Authorizations:
BearerAuth
query Parameters
offset
integer [ 0 .. 1000000 ]

The number of items to skip before starting to collect the result set. Default is 0.

limit
integer [ 1 .. 1000 ]

The numbers of items to return. Default is 50.

created.gte
string <ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS)>
Example: created.gte=2021-10-13T10:26:18

If passed, return only payments created at or after the specified time

created.lt
string <ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS)>
Example: created.lt=2021-10-13T10:39:34

If passed, return only payments created strictly before the specified time

updated.gte
string <ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS)>
Example: updated.gte=2021-10-13T10:26:18

If passed, return only payments updated at or after the specified time

updated.lt
string <ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS)>
Example: updated.lt=2021-10-13T10:39:34

If passed, return only payments updated strictly before the specified time

referenceId.eq
string
Example: referenceId.eq=order-12345

If passed, return only payments with the requested referenceId

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00",
  • "status": 200,
  • "hasMore": true,
  • "result": [
    ]
}

Create payment

Payment request, used for DEPOSITS, WITHDRAWALS and REFUNDS

Authorizations:
BearerAuth
Request Body schema: application/json
required

Payment Request - Request to initiate a payment

referenceId
string <= 256 characters

Reference assigned by Merchant. Will not go outside the system. Will be sent unchanged in the PaymentResponse.

paymentType
required
string (PaymentType)
Enum: "DEPOSIT" "WITHDRAWAL" "REFUND"

Payment Type

paymentMethod
string (PaymentMethod)
Enum: "BASIC_CARD" "CRYPTO" "FLEXEPIN" "MACROPAY" "SKRILL" "PAYRETAILERS" "LOCALPAYMENT" "MONNET" "PAYPAL" "NETELLER" "TRUSTPAYMENTS" "PAYMAXIS" "GATE8TRANSACT" "TINK" "B2BINPAY" "CLICK" "MONETIX" "PERFECTMONEY" "VOLT" "KESSPAY" "BILLLINE" "NGENIUS" "ASTROPAY" "ALYCEPAY" "PIX" "BOLETO" "UPI" "PAYTM" "NETBANKING" "FINRAX" "SPOYNT" "XINPAY" "OMNIMATRIX" "DPOPAY" "EXTERNAL_HPP" "XANPAY" "INRPAY" "ARI10" "SOFORT" "GIROPAY" "PAYSAFECARD" "PAYSAFECASH" "OPEN_BANKING" "KLARNA" "SPEI" "PAYCASH" "RAPIPAGO" "PAGOFACIL" "RAPIDTRANSFER" "MOBILE_MONEY" "INTERAC" "INTERAC_ETO" "INTERAC_RTO" "INTERAC_ACH" "PICPAY" "MOLLIE" "TED" "ZIPAY" "PSE" "EFECTY" "BANKTRANSFER" "BANKTRANSFER_AR" "BANKTRANSFER_CL" "BANKTRANSFER_CO" "BANKTRANSFER_MX" "BANKTRANSFER_PE" "BANKTRANSFER_TR" "PEC" "OXXO" "WEBPAY" "PAGOEFECTIVO" "MIFINITY" "PAYPORT" "JETONCASH" "JETONWALLET" "NEOSURF" "NODA" "NODA_REVOLUT" "ALFAKIT" "PAYFUN" "EMANAT" "M10" "RUBPAY" "MONERCHY" "MUCHBETTER" "YAPILY" "INAI" "IMPS" "RTGS" "PAYID" "ZOTAPAY" "SBP" "SBP_CROSS_BORDER" "P2P_CARD" "P2P_IBAN" "P2P_SBP" "P2P_MOBILE" "P2P_M10" "P2P_EMANAT" "P2P_KAPITAL" "P2P_ACCESS" "P2P_CROSS_BORDER" "PUSH" "GATEIQ" "VIETTEL" "ZALO" "QR" "CUP" "CODI" "PAY2PLAY" "BKASH" "NAGAD" "ROCKET" "VIRTUAL_ACCOUNT" "MULTIBANCO" "BLIK" "MBWAY" "P24" "MISTERCASH" "MACH" "KHIPU" "NEFT" "STICPAY" "SBERPAY" "MOBILE_COMMERCE" "BINANCE_PAY" "MPAY" "CHEK" "KLAP_EFECTIVO" "KLAP_TRANSFERENCIA" "PAGO46" "HITES" "SERVIFACIL" "OPENPAYD" "FAWRY" "EPS" "IDEAL" "TRUSTLY" "USSD" "MPESA" "ENAIRA" "ONEVOUCHER" "BANCONTACT" "SWISH" "EFT" "GCASH" "PAYMAYA" "PAGO_MOVIL" "PAGO_MOVIL_INST" "BIOPAGO" "CASH" "VOUCHERRY" "SOFT2PAY" "APPLEPAY" "GOOGLEPAY" "BRITE" "VOUCHSTAR" "REVOLUT" "ONLINE_BANKING" "PROMPTPAY" "TRUEMONEY" "MOMOPAY_VN" "MOMOPAY_RW" "VNPAY_QR" "N26" "WISE" "PAYDO_WALLET" "PAPARA" "PAYPAY" "PARAZULA" "PAYFIX" "PHONEPE" "CIP" "BASIC_CARD_HPP" "WAVE" "PIASTRIX" "DANA" "SHOPEEPAY" "QRIS" "OVO" "ALFAMART" "GOPAY" "CASHLIB" "YAPE" "PAYNOW" "MERCADOPAGO" "DRAGON_PAY" "FPX" "HAVALE" "MEFETE" "POPY" "NEQUI" "JAZZCASH" "EASYPAISA" "TRANSFIYA" "KBZ" "BYBIT_PAY" "HELP2PAY" "SEPA" "FPS" "PAYOUT_SEPA_BATCH" "PAYOUT_NONSEPA_REQUEST"

Payment Method

amount
number multiple of 1e-18 [ 0.00001 .. 1000000000 ]

Payment amount

currency
required
string <ISO 4217 code for FIAT currencies or cryptocurrency symbol>

Payment currency

parentPaymentId
string <= 32 characters

Id of initial deposit for refunds, Id of initial recurring payment for subsequent payments

description
string <= 512 characters

Description of the transaction shown to the Customer. Can be sent outside the system.

object (Card)

You must be PCI DSS compliant to collect card data on your side. If you are not certified, do not add this field to your request and we will collect the data on our page.

object (Customer)
object (BillingAddress)

Customer's billing address

returnUrl
string <= 256 characters

URL to redirect Customer after processing

webhookUrl
string

Url to receive payment status notifications

startRecurring
boolean

Send 'true' if you want this payment to initiate recurring chain. Default is 'false'.

preAuth
boolean

Send 'true' if you want to request a Pre-Authorization charge (initiate a 2-phase deposit).

recurringToken
string

To continue recurring chain, send a token from a previously initiated recurring payment.

object (SubscriptionRequest)

Subscription to bill customers at regular intervals. Used only with 'startRecurring=true'.

object

Additional parameters required by some payment providers. Contact support for more information.

Responses

Request samples

Content type
application/json
Example
{
  • "paymentType": "DEPOSIT",
  • "currency": "EUR"
}

Response samples

Content type
application/json
Example
{}

Find payment

Find payment by Id

Authorizations:
BearerAuth
path Parameters
id
required
string/[a-zA-Z0-9]{32}/

Payment Id

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00",
  • "status": 200,
  • "result": {
    }
}

Execute deposit

Execute deposit without customer redirection to gateway checkout page. Consult with support team before using this method.

Authorizations:
BearerAuth
path Parameters
id
required
string/[a-zA-Z0-9]{32}/

Payment Id

Request Body schema: application/json
required

Subscription patch request

customerIp
required
string <= 39 characters

Customer IP address. Both v4 and v6 addresses are supported.

ipCountryCode
string = 2 characters

Country of the specified customer IP address

customerUserAgent
string <= 512 characters

User agent string for the browser. Equals the navigator.userAgent parameter in JavaScript.

browserWindowWidth
integer

Browser window width in pixels. Equals the document.body.clientWidth parameter in JavaScript.

browserWindowHeight
integer

Browser window height in pixels. Equals the document.body.clientHeight parameter in JavaScript.

browserScreenWidth
integer

Screen width in pixels. Equals the screen.width parameter in JavaScript.

browserScreenHeight
integer

Screen height in pixels. Equals the screen.height parameter in JavaScript.

browserScreenColorDepth
integer

Screen color depth in bits per pixel. Equals the screen.colorDepth parameter in JavaScript.

browserLanguage
string <= 32 characters

Language of the navigator. Equals the navigator.language parameter in JavaScript.

browserJavaEnabled
boolean <= 39 characters

Indicates if the browser is Java-enabled or not. Equals the navigator.javaEnabled() parameter in JavaScript.

browserTimezoneOffset
integer

Time zone difference, in minutes, from the current locale to UTC. Equals the new Date().getTimezoneOffset() parameter in JavaScript.

Responses

Request samples

Content type
application/json
{
  • "customerIp": "152.13.130.125"
}

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00",
  • "status": 200,
  • "result": {
    }
}

Capture payment

Capture a Pre-Authorized payment fully or partially. Only a payment in AUTHORIZED state can be captured.

Authorizations:
BearerAuth
path Parameters
id
required
string/[a-zA-Z0-9]{32}/

Payment Id

Request Body schema: application/json
optional

Capture Request - Request to capture a Pre-Authorized payment

amount
number multiple of 1e-18 [ 0.00001 .. 1000000000 ]

Capture amount. Should not exceed the authorized payment amount. If not specified, the authorized payment amount will be captured fully.

Responses

Request samples

Content type
application/json
{
  • "amount": 11.12
}

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00",
  • "status": 200,
  • "result": {
    }
}

Void payment

Void a Pre-Authorized payment. Only a payment in AUTHORIZED state can be voided. The payment will be transferred to CANCELLED state and will no longer be available for capturing.

Authorizations:
BearerAuth
path Parameters
id
required
string/[a-zA-Z0-9]{32}/

Payment Id

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00",
  • "status": 200,
  • "result": {
    }
}

Get operations

Get a list of operations performed during payment processing sorted by time (most recent first)

Authorizations:
BearerAuth
path Parameters
id
required
string/[a-zA-Z0-9]{32}/

Payment Id

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00",
  • "status": 200,
  • "result": [
    ]
}

Subscriptions

Subscriptions API

Find subscription

Find subscription by Id

Authorizations:
BearerAuth
path Parameters
id
required
string/[a-zA-Z0-9]{32}/

Subscription Id

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00",
  • "status": 200,
  • "result": {
    }
}

Patch subscription

Patch subscription

Authorizations:
BearerAuth
path Parameters
id
required
string/[a-zA-Z0-9]{32}/

Subscription Id

Request Body schema: application/json
required

Subscription patch request

state
string
Value: "CANCELLED"

New subscription state

Responses

Request samples

Content type
application/json
{
  • "state": "CANCELLED"
}

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00",
  • "status": 200,
  • "result": {
    }
}

Balances

Withdrawal balances API

Get withdrawal balances

Get a list of funds available for withdrawal by currency (see "Check Withdrawal Balance" in shop settings)

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00",
  • "status": 200,
  • "result": [
    ]
}