Retrieve a payment

curl --request GET \
  --url https://api.bango.com/ns/{nsid}/payments/{ridOrAlias} \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.bango.com/ns/{nsid}/payments/{ridOrAlias}', 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/{ridOrAlias}"

headers = {"Authorization": "Basic <encoded-value>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "rid": "581b2e40-741c-4683-ae66-46c9fe6f4d5e",
  "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"
  },
  "lastUpdate": "2022-12-21T08:59:32Z",
  "balance": {
    "authorized": {
      "amount": 999,
      "currency": "USD"
    },
    "captured": {
      "amount": 999,
      "currency": "USD"
    },
    "refunded": {
      "amount": 999,
      "currency": "USD"
    },
    "canceled": {
      "amount": 999,
      "currency": "USD"
    }
  },
  "paymentState": "creating",
  "processingState": "idle",
  "result": {
    "code": "charge-denied",
    "reasons": [
      {
        "code": "missing-parameter",
        "meta": {
          "param": "<string>"
        },
        "message": "A required parameter was missing from the request",
        "url": "https://developer.bango.com/error-codes/missing-parameter"
      }
    ]
  },
  "currentAction": {
    "type": "CREATE",
    "payload": {}
  },
  "partnerPaymentId": "asdfg-asdfhj-fgrewa-bcczx",
  "partnerRequestId": "zfknveriuouzxcqweff12tgdvxxzb0",
  "paymentProviderPaymentId": "345hkjhsgdkfgh43k5hjkhk1",
  "shared": {
    "merchantToPaymentProvider": {}
  }
}

{
  "errors": [
    {
      "code": "invalid-credentials",
      "meta": {},
      "message": "The supplied credentials are not valid",
      "url": "https://developer.bango.com/error-codes/invalid-credentials"
    }
  ]
}

{
  "errors": [
    {
      "code": "permission-denied",
      "meta": {},
      "message": "The client is not permitted to perform this operation",
      "url": "https://developer.bango.com/error-codes/permission-denied"
    }
  ]
}

{
  "errors": [
    {
      "code": "not-found",
      "meta": {},
      "message": "The requested resource was not found",
      "url": "https://developer.bango.com/error-codes/not-found"
    }
  ]
}

{
  "errors": [
    {
      "code": "too-many-requests",
      "meta": {},
      "message": "Request limit reached. Please try again later",
      "url": "https://developer.bango.com/error-codes/too-many-requests"
    }
  ]
}

{
  "errors": [
    {
      "code": "internal-server-error",
      "meta": {
        "canRetry": true
      },
      "message": "The server encountered an unexpected condition which prevented it from fulfilling the request",
      "url": "https://developer.bango.com/error-codes/internal-server-error"
    }
  ]
}

{
  "errors": [
    {
      "code": "service-unavailable",
      "meta": {},
      "message": "The service is undergoing maintenance and is not available. Please try again later",
      "url": "https://developer.bango.com/error-codes/service-unavailable"
    }
  ]
}

Retrieve a payment

Use this endpoint to retrieve a payment. The paymentState, processingState, and currentAction properties of the resource describe the current state of the payment and any operations currently taking place on the payment. These values change over time. Partners can use this endpoint to poll a payment regularly to track asynchronous processes managed by the Bango Platform, such as requests to a downstream payment provider.

To poll, partners can:

Use the rid of the payment: this is a unique identifier (UUID v4) created by the Bango Platform
Use an alias for the rid, for example partnerPaymentId:ahskdfiu234. (The Bango Platform creates this alias automatically if the partner specifies a partnerPaymentId when creating the payment)

GET

https://api.bango.com

{nsid}

payments

{ridOrAlias}

Retrieve a payment

curl --request GET \
  --url https://api.bango.com/ns/{nsid}/payments/{ridOrAlias} \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.bango.com/ns/{nsid}/payments/{ridOrAlias}', 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/{ridOrAlias}"

headers = {"Authorization": "Basic <encoded-value>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "rid": "581b2e40-741c-4683-ae66-46c9fe6f4d5e",
  "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"
  },
  "lastUpdate": "2022-12-21T08:59:32Z",
  "balance": {
    "authorized": {
      "amount": 999,
      "currency": "USD"
    },
    "captured": {
      "amount": 999,
      "currency": "USD"
    },
    "refunded": {
      "amount": 999,
      "currency": "USD"
    },
    "canceled": {
      "amount": 999,
      "currency": "USD"
    }
  },
  "paymentState": "creating",
  "processingState": "idle",
  "result": {
    "code": "charge-denied",
    "reasons": [
      {
        "code": "missing-parameter",
        "meta": {
          "param": "<string>"
        },
        "message": "A required parameter was missing from the request",
        "url": "https://developer.bango.com/error-codes/missing-parameter"
      }
    ]
  },
  "currentAction": {
    "type": "CREATE",
    "payload": {}
  },
  "partnerPaymentId": "asdfg-asdfhj-fgrewa-bcczx",
  "partnerRequestId": "zfknveriuouzxcqweff12tgdvxxzb0",
  "paymentProviderPaymentId": "345hkjhsgdkfgh43k5hjkhk1",
  "shared": {
    "merchantToPaymentProvider": {}
  }
}

{
  "errors": [
    {
      "code": "invalid-credentials",
      "meta": {},
      "message": "The supplied credentials are not valid",
      "url": "https://developer.bango.com/error-codes/invalid-credentials"
    }
  ]
}

{
  "errors": [
    {
      "code": "permission-denied",
      "meta": {},
      "message": "The client is not permitted to perform this operation",
      "url": "https://developer.bango.com/error-codes/permission-denied"
    }
  ]
}

{
  "errors": [
    {
      "code": "not-found",
      "meta": {},
      "message": "The requested resource was not found",
      "url": "https://developer.bango.com/error-codes/not-found"
    }
  ]
}

{
  "errors": [
    {
      "code": "too-many-requests",
      "meta": {},
      "message": "Request limit reached. Please try again later",
      "url": "https://developer.bango.com/error-codes/too-many-requests"
    }
  ]
}

{
  "errors": [
    {
      "code": "internal-server-error",
      "meta": {
        "canRetry": true
      },
      "message": "The server encountered an unexpected condition which prevented it from fulfilling the request",
      "url": "https://developer.bango.com/error-codes/internal-server-error"
    }
  ]
}

{
  "errors": [
    {
      "code": "service-unavailable",
      "meta": {},
      "message": "The service is undergoing maintenance and is not available. Please try again later",
      "url": "https://developer.bango.com/error-codes/service-unavailable"
    }
  ]
}

Authorizations

Authorization

string

header

required

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

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"

ridOrAlias

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"

Response

Resource found

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

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"

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

Retrieve a payment

Authorizations

Path Parameters

Response