Create a payment

curl --request POST \
  --url https://api.bango.com/ns/{nsid}/payments \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "paymentInstrumentToken": "65ea5204-f1c1-463d-9eab-da7977960e2d",
  "saleItem": {
    "description": "Ognab Music - 6-month subscription",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "category": "<string>",
    "uniqueId": "18c32e64-04dc-4886-83f1-1a7d7ac1a95b"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    paymentInstrumentToken: '65ea5204-f1c1-463d-9eab-da7977960e2d',
    saleItem: {
      description: 'Ognab Music - 6-month subscription',
      price: {amount: 999, currency: 'USD'},
      category: '<string>',
      uniqueId: '18c32e64-04dc-4886-83f1-1a7d7ac1a95b'
    }
  })
};

fetch('https://api.bango.com/ns/{nsid}/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bango.com/ns/{nsid}/payments"

payload = {
    "paymentInstrumentToken": "65ea5204-f1c1-463d-9eab-da7977960e2d",
    "saleItem": {
        "description": "Ognab Music - 6-month subscription",
        "price": {
            "amount": 999,
            "currency": "USD"
        },
        "category": "<string>",
        "uniqueId": "18c32e64-04dc-4886-83f1-1a7d7ac1a95b"
    }
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "rid": "9a84f3fb-d70f-45e6-aff8-311216dc93e1",
  "paymentInstrumentToken": "54f23474-18a5-4093-ad22-8f8335878635",
  "saleItem": {
    "description": "Ognab Music",
    "category": "DIGITAL_GOODS",
    "price": {
      "amount": 995,
      "currency": "USD"
    }
  },
  "partnerPaymentId": "Opaque_String_Of_Any_Format_1234",
  "lastUpdate": "2023-02-21T17:45:39Z",
  "balance": {
    "authorized": {
      "amount": 0,
      "currency": "USD"
    },
    "captured": {
      "amount": 0,
      "currency": "USD"
    },
    "refunded": {
      "amount": 0,
      "currency": "USD"
    },
    "canceled": {
      "amount": 0,
      "currency": "USD"
    }
  },
  "paymentState": "new",
  "processingState": "idle",
  "result": null,
  "currentAction": null
}

Create a payment

Use this endpoint to create a payment.

Include the action property to send an action immediately after the payment resource is created.

On a successful creation, the Bango Platform can automatically create an alias that merchants can use to retrieve payments and perform updates. For example, if the merchant sets partnerPaymentId to aoieroiu234oiu in the create request, it can later use partnerPaymentId:aoieroiu234oiu in GET and POST requests in place of the rid path parameter. The prefix partnerPaymentId is mandatory in this case.

400 response error codes:

invalid-json if the request body isn’t valid JSON format
missing-parameter for any mandatory parameter missing from the request body
invalid-parameter for any parameter that’s syntactically or semantically incorrect. For example:
- If this specification defines a parameter as a string, and an array of strings is supplied
- If this specification defines a parameter as a datetime, and an invalid datetime is supplied
- If parameters should be in a particular order (eg chronological datetimes) and they aren’t

POST

https://api.bango.com

{nsid}

payments

Create a payment

curl --request POST \
  --url https://api.bango.com/ns/{nsid}/payments \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "paymentInstrumentToken": "65ea5204-f1c1-463d-9eab-da7977960e2d",
  "saleItem": {
    "description": "Ognab Music - 6-month subscription",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "category": "<string>",
    "uniqueId": "18c32e64-04dc-4886-83f1-1a7d7ac1a95b"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    paymentInstrumentToken: '65ea5204-f1c1-463d-9eab-da7977960e2d',
    saleItem: {
      description: 'Ognab Music - 6-month subscription',
      price: {amount: 999, currency: 'USD'},
      category: '<string>',
      uniqueId: '18c32e64-04dc-4886-83f1-1a7d7ac1a95b'
    }
  })
};

fetch('https://api.bango.com/ns/{nsid}/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bango.com/ns/{nsid}/payments"

payload = {
    "paymentInstrumentToken": "65ea5204-f1c1-463d-9eab-da7977960e2d",
    "saleItem": {
        "description": "Ognab Music - 6-month subscription",
        "price": {
            "amount": 999,
            "currency": "USD"
        },
        "category": "<string>",
        "uniqueId": "18c32e64-04dc-4886-83f1-1a7d7ac1a95b"
    }
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "rid": "9a84f3fb-d70f-45e6-aff8-311216dc93e1",
  "paymentInstrumentToken": "54f23474-18a5-4093-ad22-8f8335878635",
  "saleItem": {
    "description": "Ognab Music",
    "category": "DIGITAL_GOODS",
    "price": {
      "amount": 995,
      "currency": "USD"
    }
  },
  "partnerPaymentId": "Opaque_String_Of_Any_Format_1234",
  "lastUpdate": "2023-02-21T17:45:39Z",
  "balance": {
    "authorized": {
      "amount": 0,
      "currency": "USD"
    },
    "captured": {
      "amount": 0,
      "currency": "USD"
    },
    "refunded": {
      "amount": 0,
      "currency": "USD"
    },
    "canceled": {
      "amount": 0,
      "currency": "USD"
    }
  },
  "paymentState": "new",
  "processingState": "idle",
  "result": null,
  "currentAction": null
}

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Headers

Idempotency-Key

string<uuid>

A unique identifier to use for idempotency purposes.

Example:

"76aa2331-a96a-4a3b-8c23-019aabb44ed1"

Path Parameters

nsid

string<uuid>

required

Globally unique namespace ID. These IDs are opaque, not guessable, and not sequential.

Bango provides each Bango partner with a unique set of resource URIs. All resource URI paths start with /ns/{nsid}, where {nsid} is the namespace ID. No other Bango partner shares this namespace. Partner credentials permit access only to URIs with this namespace.

Example:

"673c74de-ce5b-4f79-9851-2544d1d836cb"

Body

application/json

Data needed to create a payment.

paymentInstrumentToken

string<uuid>

required

A unique identifier for a payment method used to charge a payment provider's end user.

To obtain a payment instrument token, use the Bango Identity Verification API.

To charge an end user using a payment instrument token, use the Bango Payments API.

Example:

"65ea5204-f1c1-463d-9eab-da7977960e2d"

saleItem

Sale item · object

required

An item (product or service) purchased in whole or part by a payment.

Show child attributes

partnerPaymentId

string

The merchant partner's own unique identifier for the payment. Not necessarily a UUID. The Bango Platform considers this an opaque value but checks for uniqueness when the payment is being created (400 error if not).

Required string length: 1 - 255

Example:

"asdfg-asdfhj-fgrewa-bcczx"

partnerRequestId

string

Merchant-owned request identifier. Bango considers this identifier opaque, and passes it to the payment provider unchanged (in OPPA request actions, as merchantPaymentId).

In a returned payment resource, the partnerRequestId reflects the value specified in the request from the merchant. If a request does not specify a partnerRequestId then the response does not include a partnerRequestId.

Required string length: 1 - 255

Example:

"zfknveriuouzxcqweff12tgdvxxzb0"

action

AUTHORIZE API action · object

Optional action to send immediately after a successful resource creation.

AUTHORIZE API action
CHARGE API action [plan-later]

Show child attributes

shared

Data shared between merchant and payment provider · object

Data shared between the merchant partner and the payment provider as part of a payment resource. Supplied to the payment provider with every payment action, such as AUTHORIZE or CHARGE.

Show child attributes

Response

Resource created.

A payment resource.

rid

string<uuid>

required

Globally unique resource ID. These IDs are opaque, not guessable, and not sequential.

Each individual resource in a partner's namespace has a unique identifier: this is the identifier immediately after the resource type in the URI path.

For example, in the URI /ns/673c74de-ce5b-4f79-9851-2544d1d836cb/elephants/581b2e40-741c-4683-ae66-46c9fe6f4d5e:

The namespace id is 673c74de-ce5b-4f79-9851-2544d1d836cbde
elephants indicates the resource type is elephant
The resource id is 581b2e40-741c-4683-ae66-46c9fe6f4d5e

Every resource has a read-only property rid that contains the resource ID, for convenience.

Example:

"581b2e40-741c-4683-ae66-46c9fe6f4d5e"

paymentInstrumentToken

string<uuid>

required

A unique identifier for a payment method used to charge a payment provider's end user.

To obtain a payment instrument token, use the Bango Identity Verification API.

To charge an end user using a payment instrument token, use the Bango Payments API.

Example:

"65ea5204-f1c1-463d-9eab-da7977960e2d"

saleItem

Sale item · object

required

An item (product or service) purchased in whole or part by a payment.

Show child attributes

lastUpdate

string<date-time>

required

RFC 3339 datetime of the last update to this resource

Example:

"2022-12-21T08:59:32Z"

balance

object

required

The total amounts currently authorized, captured, refunded, and canceled for the payment, taking all successful actions into account. Values exclude any requests awaiting a response from the downstream payment provider.

For one-step payments (the CHARGE action), the authorized and captured values are always identical.

Show child attributes

paymentState

enum<string>

required

The high-level view of the progress of the payment through the standard lifecycle. Allowed values are:

creating - the partner requested a new payment resource but the request has not yet been approved
new - the payments system approved a request to create a payment resource and there are no approved authorization/capture/charge/refund events. Balances: authorized == 0, captured == 0, refunded == 0
authorized - the payments system approved a request to create a payment resource and there's at least one approved authorization event, but no captures, charges, or refunds. Balances: authorized > 0, captured == 0, refunded == 0
captured - the payments system approved a request to create a payment resource and there's at least one approved authorization/capture/charge event, and maybe some refunds, and the payment isn't fully refunded. Balances: authorized > 0, captured > 0, refunded >= 0, captured > refunded
refunded - the payments system approved a request to create a payment resource and the payment is fully refunded. Balances: authorized > 0, captured > 0, refunded > 0, captured == refunded
closed - the payment resource is effectively frozen. No actions will be processed.

Available options:

creating,

new,

authorized,

captured,

refunded,

closed

processingState

enum<string>

required

Indicates whether the Bango Platform is:

preparing: preparing to process a partner action, and NOT ready to receive a new action
processing: processing a partner action (including waiting for a response from the downstream payment provider), and NOT ready to receive a new action
idle: NOT currently processing a partner action, and ready to receive a new action

While processingState is preparing or processing, the Bango Platform will reject any new action for this payment resource.

Available options:

idle,

preparing,

processing

result

null | Result of the most recent action · object

required

The result of the most recent action, if any.

Show child attributes

currentAction

CREATE pseudo-API action · object

required

An internal action that occurs automatically when the merchant partner creates the payment. A merchant can't send this action explicitly.

Show child attributes

partnerPaymentId

string

Required string length: 1 - 255

Example:

"asdfg-asdfhj-fgrewa-bcczx"

partnerRequestId

string

Merchant-owned request identifier. Bango considers this identifier opaque, and passes it to the payment provider unchanged (in OPPA request actions, as merchantPaymentId).

Required string length: 1 - 255

Example:

"zfknveriuouzxcqweff12tgdvxxzb0"

paymentProviderPaymentId

string

The payment provider's own unique identifier for the payment. Not necessarily a UUID. Bango assumes it is unique.

The payment provider may supply this value in response to a request from the Bango Platform. Subsequent requests to the payment provider include the value where relevant, and responses to the Bango Platform may replace the value.

The current value is given to the merchant in the payment resource.

Required string length: 1 - 255

Example:

"345hkjhsgdkfgh43k5hjkhk1"

shared

Data shared between merchant and payment provider · object

Data shared between the merchant partner and the payment provider as part of a payment resource. Supplied to the payment provider with every payment action, such as AUTHORIZE or CHARGE.

Show child attributes

Bango Payments

For payment providers

For merchants

Create a payment

Authorizations

Headers

Path Parameters

Body

Response