Update a payment

curl --request POST \
  --url https://api.bango.com/ns/{nsid}/payments/{ridOrAlias}/actions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "AUTHORIZE",
  "payload": {
    "partnerRequestId": "zfknveriuouzxcqweff12tgdvxxzb0",
    "locale": "en-US"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'AUTHORIZE',
    payload: {partnerRequestId: 'zfknveriuouzxcqweff12tgdvxxzb0', locale: 'en-US'}
  })
};

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

payload = {
    "type": "AUTHORIZE",
    "payload": {
        "partnerRequestId": "zfknveriuouzxcqweff12tgdvxxzb0",
        "locale": "en-US"
    }
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, 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-json",
      "meta": {},
      "message": "The request body is not valid JSON",
      "url": "https://developer.bango.com/error-codes/invalid-json"
    }
  ]
}

{
  "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": "request-in-progress",
      "meta": {},
      "message": "Request currently in progress: try again after a short delay",
      "url": "https://developer.bango.com/error-codes/request-in-progress"
    }
  ]
}

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

Update a payment

Use this endpoint to update a payment and/or to trigger tasks related to a payment.

API consumers request updates by sending actions to this endpoint. An action specifies what you want to do to the resource. The Bango Platform decides whether the action is permitted, and if so it performs the action. An action might result in a change to the resource’s properties, and might cause a side effect. Actions are logged as *_REQUESTED events. The Bango Platform also logs events recording whether the action succeeded or failed.

An action might be syntactically valid but not permitted at the time the partner sends it, depending on various factors. These factors include:

Whether the Bango Platform is already processing an action
Whether the partner is permitted to perform the action when the payment resource is in its current state (for example, a specific policy applies to the partner that doesn’t apply to all partners)
Whether the action makes sense in the current state (for example, a request to capture more than authorized will be rejected)

These types of actions DO NOT cause a 400 error. Instead, the resource returned in the response contains a result property. This indicates how the Bango Platform treated the request.

To send an action, 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)

400 response error codes:

invalid-json if the request body isn’t valid JSON format
missing-parameter if type is not present in the request body
invalid-parameter if type is not a valid action type
missing-parameter if payload is required and not present
invalid-parameter if payload is not the expected shape for the type of action (which may mean that payload is missing required parameters or some parameters are invalid: check the documentation to find out the expected payload shape for each action type)

POST

https://api.bango.com

{nsid}

payments

{ridOrAlias}

actions

Update a payment

curl --request POST \
  --url https://api.bango.com/ns/{nsid}/payments/{ridOrAlias}/actions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "AUTHORIZE",
  "payload": {
    "partnerRequestId": "zfknveriuouzxcqweff12tgdvxxzb0",
    "locale": "en-US"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'AUTHORIZE',
    payload: {partnerRequestId: 'zfknveriuouzxcqweff12tgdvxxzb0', locale: 'en-US'}
  })
};

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

payload = {
    "type": "AUTHORIZE",
    "payload": {
        "partnerRequestId": "zfknveriuouzxcqweff12tgdvxxzb0",
        "locale": "en-US"
    }
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, 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-json",
      "meta": {},
      "message": "The request body is not valid JSON",
      "url": "https://developer.bango.com/error-codes/invalid-json"
    }
  ]
}

{
  "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": "request-in-progress",
      "meta": {},
      "message": "Request currently in progress: try again after a short delay",
      "url": "https://developer.bango.com/error-codes/request-in-progress"
    }
  ]
}

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

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"

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"

Body

application/json

A request to update a payment and trigger session-related tasks. A request specifies an action type and any action-specific data (the payload).

The following action types are available. See each action type schema for detailed information.

AUTHORIZE: A request to reserve funds from a payment provider's end user (two-step payment, step 1)
CAPTURE: A request to capture funds from a payment provider's end user (two-step payment, step 2)
REFUND: A request to refund an amount to a payment provider's end user
CANCEL_AUTH: A request to release funds reserved from a payment provider's end user
CHARGE: A request to capture funds from a payment provider's end user (one-step payment)

Whether an action has any effect depends on the current state value of the session, and other factors. The response to this request is the session resource: the state property might have changed as a result of the request.

AUTHORIZE API action
CANCEL_AUTH API action
CAPTURE API action
CHARGE API action [plan-later]
REFUND API action

A request to reserve funds from a payment provider's end user (two-step payment, step 1). The request may be denied (for example, if the amount to reserve is too great).

To authorize an amount less than or equal to the payment resource's saleItem.price property, set payload.amount and payload.currency to the amount to authorize.

To authorize the saleItem.price, omit both payload.amount and payload.currency or set them explicitly to the values in saleItem.price.

The optional locale is passed to the payment provider.

type

any

required

payload

Authorize full amount, optional locale · object

required

Authorize the full amount specified in the payment resource's saleItem.price property, and optionally specify the merchant end user's locale and a request ID

Authorize full amount, optional locale
Authorize specific amount, optional locale

Show child attributes

Response

The updated resource.

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

Update a payment

Authorizations

Headers

Path Parameters

Body

Response