> ## Documentation Index > Fetch the complete documentation index at: https://docs.bango.com/llms.txt > Use this file to discover all available pages before exploring further. # Send an action to the payment provider [adapter] > The Bango Platform uses this endpoint to send an action to a payment provider, or an adapter for a payment provider. The available actions constitute a small fixed vocabulary for communications initiated by the Bango Platform. An action can: - Ask the payment provider [adapter] to perform an operation - Request data from the payment provider [adapter] - Notify the payment provider [adapter] of an event of interest Every action sent (a _request action_) may result in a range of possible responses (_response actions_) from the payment provider [adapter]. Each request action defines the expected response actions. Every request action will include a unique `id` property (UUID v4). This identifies the request action and is not used for any other purpose (it's **not** a payment resource ID, for example). The response action corresponding to the request action must include the request action's `id`. ### HTTP responses The Bango Platform always sends a request to the payment provider [adapter] over HTTP, and the payment provider [adapter] must return an HTTP response. HTTP requests contain request actions as defined in this specification. The HTTP response MUST be one of the following: - HTTP 204 NO CONTENT - permitted only if the request needs a simple acknowledgement without specific response data - HTTP 200 OK - containing a response action in the response body. Each request action defines the expected response actions - HTTP 4xx - indicating a problem with the request action - HTTP 5xx - indicating a problem with the payment provider [adapter] system This specification defines the shape of HTTP 4xx and 5xx responses. These all have a response body containing an `errors` array, each member of which is an object containing an error `code` and other data. If a request to a payment provider [adapter] times out, this is treated the same as an HTTP 503 error from the payment provider [adapter] with `canRetry: true`. #### HTTP 400 BAD REQUEST responses For HTTP 400 BAD REQUEST responses specifically, the payment provider [adapter] MUST use these values for `code` for the error conditions listed: - `invalid-json` - If the request body isn't valid JSON format - `missing-parameter` - If any required parameter is not present in the request body. For example, `id`, `type`, `payload`, or any required value inside `payload`. - `invalid-parameter` - If any parameter in the request is syntactically invalid. For example, if `type` is an integer, or if `id` is not a UUID v4 - If any parameter in the request is semantically invalid. For example, if a `payload` field specifies a user identifier and that user isn't recognized by the payment provider [adapter] The payment provider [adapter] MAY use other values of `code` for an HTTP 400 BAD REQUEST response with other error conditions. The specification for each request action defines the additional permitted values of `code`. #### HTTP 5xx responses HTTP 5xx responses indicate a problem with the payment provider [adapter]. This might be a temporary problem caused by a network issue between the Bango Platform and the payment provider [adapter], or it may indicate a more serious, persistent issue. Any 5xx response from the payment provider [adapter] propagates through the platform as a service error with code `payment-provider-failure`. The 5xx response from the payment provider [adapter] may specify that the request can be retried, using the `meta.canRetry` boolean in the 5xx response. A timeout in the connection from the Bango Platform to the payment provider [adapter] is always reported as a `payment-provider-failure` that may be retried. ## OpenAPI ````yaml /openapi/current/dcb-payments/bango-to-payment-provider/openapi.yaml post /actions openapi: 3.1.0 info: title: Outbound Payment Provider API version: 1.0.{build_number} x-bango-public-version: 1.0.0 contact: name: Bango Support url: https://developer.bango.com email: support@bango.com x-bango-public-description: > The Outbound Payment Provider API (OPPA) is an interface definition for a service that payment providers implement on their own servers. It defines how the Bango Platform sends _actions_ to payment providers. An action represents a request for the payment provider to perform an operation, or a request for the payment provider to provide some data, or a notification to the payment provider. ### Glossary - **payment provider [adapter]**: Some payment providers integrate directly with the Bango Platform, and some integrate indirectly with the help of a Bango-hosted adapter service. We use the phrase "payment provider [adapter]" to mean *either* the payment provider *or* a Bango-hosted adapter for that payment provider ## Change log - 1.0.0 - First released version servers: - url: https://payment-provider.example.com/any-prefix description: Server belonging to the payment provider [adapter] security: - BasicAuth: [] paths: /actions: post: summary: Send an action to the payment provider [adapter] description: > The Bango Platform uses this endpoint to send an action to a payment provider, or an adapter for a payment provider. The available actions constitute a small fixed vocabulary for communications initiated by the Bango Platform. An action can: - Ask the payment provider [adapter] to perform an operation - Request data from the payment provider [adapter] - Notify the payment provider [adapter] of an event of interest Every action sent (a _request action_) may result in a range of possible responses (_response actions_) from the payment provider [adapter]. Each request action defines the expected response actions. Every request action will include a unique `id` property (UUID v4). This identifies the request action and is not used for any other purpose (it's **not** a payment resource ID, for example). The response action corresponding to the request action must include the request action's `id`. ### HTTP responses The Bango Platform always sends a request to the payment provider [adapter] over HTTP, and the payment provider [adapter] must return an HTTP response. HTTP requests contain request actions as defined in this specification. The HTTP response MUST be one of the following: - HTTP 204 NO CONTENT - permitted only if the request needs a simple acknowledgement without specific response data - HTTP 200 OK - containing a response action in the response body. Each request action defines the expected response actions - HTTP 4xx - indicating a problem with the request action - HTTP 5xx - indicating a problem with the payment provider [adapter] system This specification defines the shape of HTTP 4xx and 5xx responses. These all have a response body containing an `errors` array, each member of which is an object containing an error `code` and other data. If a request to a payment provider [adapter] times out, this is treated the same as an HTTP 503 error from the payment provider [adapter] with `canRetry: true`. #### HTTP 400 BAD REQUEST responses For HTTP 400 BAD REQUEST responses specifically, the payment provider [adapter] MUST use these values for `code` for the error conditions listed: - `invalid-json` - If the request body isn't valid JSON format - `missing-parameter` - If any required parameter is not present in the request body. For example, `id`, `type`, `payload`, or any required value inside `payload`. - `invalid-parameter` - If any parameter in the request is syntactically invalid. For example, if `type` is an integer, or if `id` is not a UUID v4 - If any parameter in the request is semantically invalid. For example, if a `payload` field specifies a user identifier and that user isn't recognized by the payment provider [adapter] The payment provider [adapter] MAY use other values of `code` for an HTTP 400 BAD REQUEST response with other error conditions. The specification for each request action defines the additional permitted values of `code`. #### HTTP 5xx responses HTTP 5xx responses indicate a problem with the payment provider [adapter]. This might be a temporary problem caused by a network issue between the Bango Platform and the payment provider [adapter], or it may indicate a more serious, persistent issue. Any 5xx response from the payment provider [adapter] propagates through the platform as a service error with code `payment-provider-failure`. The 5xx response from the payment provider [adapter] may specify that the request can be retried, using the `meta.canRetry` boolean in the 5xx response. A timeout in the connection from the Bango Platform to the payment provider [adapter] is always reported as a `payment-provider-failure` that may be retried. operationId: send-action-outbound parameters: - in: header name: Bango-Request-Action schema: description: > The value of `type` from the request body, indicating the type of request action. Allows payment providers [adapters] to route request actions without inspecting the request body. type: string enum: - NOTIFY_SESSION_FLOW - AUTHORIZE - CAPTURE - REFUND - CANCEL_AUTH - CHARGE - GET_ELIGIBILITY - SEND_MT_MESSAGE - VALIDATE_PASSPHRASE - SEND_OTP - VERIFY_OTP requestBody: description: > An action initiated by the Bango Platform, to be processed by the payment provider [adapter]. The following action types are available. See each action type schema for detailed information on purpose and response action types. - `NOTIFY_SESSION_FLOW`: Tell the payment provider [adapter] that a merchant partner is starting an identity verification flow - `AUTHORIZE`: Ask the payment provider [adapter] for payment authorization: the first step in a two-step (Authorize/Capture) payments model. - `CAPTURE`: Ask the payment provider [adapter] for payment capture: the second step in a two-step (Authorize/Capture) payments model - `REFUND`: Ask the payment provider [adapter] to charge a payment request: one-step payments model - `CANCEL_AUTH`: Ask the payment provider [adapter] to cancel an authorization on a payment request. - `GET_ELIGIBILITY`: Ask the payment provider [adapter] for up-to-date eligibility data for an end user - `SEND_MT_MESSAGE`: Ask the payment provider [adapter] to send a message to a particular end user device - `VALIDATE_PASSPHRASE`: Ask the payment provider [adapter] to validate a passphrase to a particular end user device - `SEND_OTP`: Ask the payment provider [adapter] to send an OTP to a particular end user device - `VERIFY_OTP`: Ask the payment provider [adapter] to verify an OTP provided by the merchant end user - `CHARGE`: Ask the payment provider [adapter] to charge a payment request: one-step payments model required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/AUTHORIZE' - $ref: '#/components/schemas/CANCEL_AUTH' - $ref: '#/components/schemas/CAPTURE' - $ref: '#/components/schemas/CHARGE' - $ref: '#/components/schemas/REFUND' - $ref: '#/components/schemas/GET_ELIGIBILITY' - $ref: '#/components/schemas/NOTIFY_SESSION_FLOW' - $ref: '#/components/schemas/SEND_MT_MESSAGE' - $ref: '#/components/schemas/VALIDATE_PASSPHRASE' - $ref: '#/components/schemas/SEND_OTP' - $ref: '#/components/schemas/VERIFY_OTP' responses: '200': description: | The response action, which depends on the request action. content: application/vnd.bango.pp-response-action.v1+json: schema: oneOf: - $ref: '#/components/schemas/GET_ELIGIBILITY_RESPONSE' - $ref: '#/components/schemas/AUTHORIZE_APPROVED_RESPONSE' - $ref: '#/components/schemas/AUTHORIZE_DENIED_RESPONSE' - $ref: '#/components/schemas/CANCEL_AUTH_APPROVED_RESPONSE' - $ref: '#/components/schemas/CANCEL_AUTH_DENIED_RESPONSE' - $ref: '#/components/schemas/CAPTURE_APPROVED_RESPONSE' - $ref: '#/components/schemas/CAPTURE_DENIED_RESPONSE' - $ref: '#/components/schemas/CHARGE_APPROVED_RESPONSE' - $ref: '#/components/schemas/CHARGE_DENIED_RESPONSE' - $ref: '#/components/schemas/REFUND_APPROVED_RESPONSE' - $ref: '#/components/schemas/REFUND_DENIED_RESPONSE' - $ref: '#/components/schemas/NOTIFY_SESSION_FLOW_APPROVED_RESPONSE' - $ref: '#/components/schemas/NOTIFY_SESSION_FLOW_DENIED_RESPONSE' - $ref: '#/components/schemas/SEND_MT_MESSAGE_RESPONSE' - $ref: '#/components/schemas/VALIDATE_PASSPHRASE_RESPONSE' - $ref: '#/components/schemas/SEND_OTP_RESPONSE' - $ref: '#/components/schemas/VERIFY_OTP_RESPONSE' '204': description: > The action in the request was acknowledged by the recipient and no response action was required '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/InvalidCredentialsErrorResponse' '403': $ref: '#/components/responses/PermissionDeniedErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' '500': description: | An internal server error occurred content: application/json: schema: type: object properties: paymentProviderOperationId: description: > An optional identifier used by the payment provider to identify retries. Used where the payment provider is unable to accept Bango's operationId. type: string minLength: 1 maxLength: 255 errors: type: array items: oneOf: - $ref: >- #/components/schemas/payment-provider-internal-server-error - $ref: '#/components/schemas/adapter-failure' required: - errors '502': $ref: '#/components/responses/PaymentProviderBadGatewayErrorResponse' '503': $ref: >- #/components/responses/PaymentProviderServiceUnavailableErrorResponse '504': $ref: '#/components/responses/PaymentProviderGatewayTimeoutErrorResponse' components: schemas: AUTHORIZE: title: AUTHORIZE request action (outbound) description: > Ask the payment provider [adapter] for payment authorization: the first step in a two-step (Authorize/Capture) payments model. This step reserves funds against the end user's payment instrument with the payment provider. How it works: merchant partners send an `AUTHORIZE` action for a payment resource. Route policy determines whether authorization is permitted. If so, OPPA will send an `AUTHORIZE` action to the payment provider [adapter]. The payment provider [adapter] responds either to approve or deny authorization (or signal an error in the request). ### Supported HTTP responses - HTTP 200 OK: - [`AUTHORIZE_APPROVED_RESPONSE`](/schemas/AUTHORIZE_APPROVED_RESPONSE) response action - [`AUTHORIZE_DENIED_RESPONSE`](/schemas/AUTHORIZE_DENIED_RESPONSE) response action - HTTP 204 NO CONTENT: - Simple acknowledgement approving authorization, without additional data - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints type: object properties: id: $ref: '#/components/schemas/request-id' type: const: AUTHORIZE payload: type: object properties: routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' paymentAction: $ref: '#/components/schemas/payment-authorize-request-properties' paymentInstrumentProperties: $ref: '#/components/schemas/payment-instrument-properties' merchantUserLocale: $ref: '#/components/schemas/locale-bcp-47' description: > A [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag representing the locale of the merchant end user, if known. additionalProperties: false required: - routeConfiguration - paymentAction - paymentInstrumentProperties idempotency: $ref: '#/components/schemas/idempotency' required: - id - type - payload CANCEL_AUTH: title: CANCEL_AUTH request action (outbound) description: > Ask the payment provider [adapter] to cancel an authorization on a payment request. The payment provider [adapter] responds either to approve or deny the cancel (or signal an error in the request). ### Supported HTTP responses - HTTP 200 OK: - [`CANCEL_AUTH_APPROVED_RESPONSE`](/schemas/CANCEL_AUTH_APPROVED_RESPONSE) response action - [`CANCEL_AUTH_DENIED_RESPONSE`](/schemas/CANCEL_AUTH_DENIED_RESPONSE) response action - HTTP 204 NO CONTENT: - Simple acknowledgement approving canceled authorization, without additional data - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints type: object properties: id: $ref: '#/components/schemas/request-id' type: const: CANCEL_AUTH payload: type: object properties: routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' paymentAction: $ref: '#/components/schemas/payment-cancel-auth-request-properties' paymentInstrumentProperties: $ref: '#/components/schemas/payment-instrument-properties' required: - routeConfiguration - paymentAction - paymentInstrumentProperties idempotency: $ref: '#/components/schemas/idempotency' required: - id - type - payload CAPTURE: title: CAPTURE request action (outbound) description: > Ask the payment provider [adapter] for payment capture: the second step in a two-step (Authorize/Capture) payments model. This step bills the end user's payment instrument with the payment provider so the merchant partner will receive the funds for the goods or services associated with the payment resource. The payment provider [adapter] responds either to approve or deny capture (or signal an error in the request). The payment resource accessible by the merchant tracks how much has been captured. Route/partner policy determines the allowed types of captures. ### Single partial capture With this policy, merchant partners may send a single `CAPTURE` action for a payment resource for which an `AUTHORIZE` action has previously succeeded. The capture may specify any amount not exceeding the full amount authorized. OPPA will send a `CAPTURE` action to the payment provider [adapter] with the requested amount, which will never exceed the amount authorized. ### Single full capture With this policy, merchant partners may send a single `CAPTURE` action for a payment resource for which an `AUTHORIZE` action has previously succeeded. The capture MUST specify the full amount authorized. OPPA will send a `CAPTURE` action to the payment provider [adapter] with the requested amount, which is always the same as the amount authorized. ### Multiple captures With this policy, merchant partners may send any number of `CAPTURE` actions for the payment resource. If the amount requested would not make the total amount captured greater than the total amount authorized, OPPA sends another `CAPTURE` action to the payment provider [adapter] with the requested amount. ### Supported HTTP responses - HTTP 200 OK: - [`CAPTURE_APPROVED_RESPONSE`](/schemas/CAPTURE_APPROVED_RESPONSE) response action - [`CAPTURE_DENIED_RESPONSE`](/schemas/CAPTURE_DENIED_RESPONSE) response action - HTTP 204 NO CONTENT: - Simple acknowledgement approving capture, without additional data - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints type: object properties: id: $ref: '#/components/schemas/request-id' type: const: CAPTURE payload: type: object properties: routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' paymentAction: $ref: '#/components/schemas/payment-capture-request-properties' paymentInstrumentProperties: $ref: '#/components/schemas/payment-instrument-properties' required: - routeConfiguration - paymentAction - paymentInstrumentProperties idempotency: $ref: '#/components/schemas/idempotency' required: - id - type - payload CHARGE: title: CHARGE request action (outbound) [plan-p1] description: > Ask the payment provider [adapter] to charge a payment request. This is a one-step payments model: it immediately bills the end user's payment instrument with the payment provider so the merchant partner will receive the funds for the goods or services associated with the payment resource, without initially reserving any funds. The payment provider [adapter] responds either to approve or deny charge (or signal an error in the request). The payment resource accessible by the merchant tracks how much has been charged in the authorized and captured balances (both will have the same value). ### Supported HTTP responses - HTTP 200 OK: - [`CHARGE_APPROVED_RESPONSE`](/schemas/CHARGE_APPROVED_RESPONSE) response action - [`CHARGE_DENIED_RESPONSE`](/schemas/CHARGE_DENIED_RESPONSE) response action - HTTP 204 NO CONTENT: - Simple acknowledgement approving charge, without additional data - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints type: object properties: id: $ref: '#/components/schemas/request-id' type: const: CHARGE payload: type: object properties: routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' paymentAction: $ref: '#/components/schemas/payment-charge-request-properties' paymentInstrumentProperties: $ref: '#/components/schemas/payment-instrument-properties' required: - routeConfiguration - paymentAction - paymentInstrumentProperties idempotency: $ref: '#/components/schemas/idempotency' required: - id - type - payload REFUND: title: REFUND request action (outbound) description: > Ask the payment provider [adapter] to refund a payment. The payment provider [adapter] responds either to approve or deny refund (or signal an error in the request). The payment resource accessible by the merchant tracks how much has been refunded. Route/partner policy determines the allowed types of refunds. ### Single partial refund With this policy, merchants may send a single `REFUND` action that specifies any amount not exceeding the full amount captured. OPPA will send a `REFUND` request action to the payment provider [adapter] with the requested amount. The amount to refund never exceeds the amount captured. ### Single full refund With this policy, merchants may send a single `REFUND` action that specifies exactly the captured amount. OPPA will send a `REFUND` request action to the payment provider [adapter] with the requested amount. ### Multiple refund With this policy, merchant partners may send any number of `REFUND` actions for the payment resource. If the amount requested would not make the total amount refunded greater than the total amount captured, OPPA sends another `REFUND` action to the payment provider [adapter] with the requested amount. ### Supported HTTP responses - HTTP 200 OK: - [`REFUND_APPROVED_RESPONSE`](/schemas/REFUND_APPROVED_RESPONSE) response action - [`REFUND_DENIED_RESPONSE`](/schemas/REFUND_DENIED_RESPONSE) response action - HTTP 204 NO CONTENT: - Simple acknowledgement approving refund, without additional data - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints type: object properties: id: $ref: '#/components/schemas/request-id' type: const: REFUND payload: type: object properties: routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' paymentAction: $ref: '#/components/schemas/payment-refund-request-properties' paymentInstrumentProperties: $ref: '#/components/schemas/payment-instrument-properties' required: - routeConfiguration - paymentAction - paymentInstrumentProperties idempotency: $ref: '#/components/schemas/idempotency' required: - id - type - payload GET_ELIGIBILITY: title: GET_ELIGIBILITY request action (outbound) description: > Ask the payment provider [adapter] for up-to-date eligibility data for an end user. The end user is identified using account properties associated with a payment instrument in the Bango Platform. ### Supported HTTP responses - HTTP 200 OK: - [`GET_ELIGIBILITY_RESPONSE`](/schemas/GET_ELIGIBILITY_RESPONSE) response action - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints - `payload.account` does not identify an end user account known to the payment provider type: object properties: id: $ref: '#/components/schemas/request-id' type: const: GET_ELIGIBILITY payload: type: object properties: routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' account: $ref: '#/components/schemas/payment-instrument-account-properties' description: | Account identification data for the end user. type: object merchantUserLocale: $ref: '#/components/schemas/locale-bcp-47' description: > A [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag representing the locale of the merchant end user, if known. additionalProperties: false required: - routeConfiguration - account required: - id - type - payload NOTIFY_SESSION_FLOW: title: NOTIFY_SESSION_FLOW request action (outbound) description: > Tell the payment provider [adapter] that a merchant partner wants to start an identity verification flow. This notification occurs when: - a billing route is configured for the merchant partner and payment provider, and - the billing route configuration enables this notification, and - the notification can simplify the identity verification flow (not all flow types use it) A payment provider [adapter] can use this action to identify and share data to the merchant partner immediately the flow starts. For example, it allows the payment provider to give the merchant a dynamically generated URL needed for the flow. How it works: merchant partners send a `START_NEGOTIATED_FLOW` action (for example) for an identity verification session resource. Route policy determines if this flow is permitted. If so, route configuration determines whether the `NOTIFY_SESSION_FLOW` OPPA action is needed. If so, OPPA sends the action to the payment provider [adapter]. The action to the payment provider [adapter] includes shared data supplied by the merchant partner. The payment provider [adapter] can validate and process the data before responding. For example, a payment provider may require a specific identifier from the merchant so it can generate an appropriate return value, or to decide whether to allow or deny the verification session. The payment provider [adapter] responds with one of the following: - A simple acknowledgment approving the flow (if it has no data to share) - An approval including data to share to the merchant partner - A denial, meaning the merchant should not be permitted to start the flow - An error (for example, if the request is malformed in some way) ### Supported HTTP responses - HTTP 200 OK: - [`NOTIFY_SESSION_FLOW_APPROVED_RESPONSE`](/schemas/NOTIFY_SESSION_FLOW_APPROVED_RESPONSE) response action - [`NOTIFY_SESSION_FLOW_DENIED_RESPONSE`](/schemas/NOTIFY_SESSION_FLOW_DENIED_RESPONSE) response action - HTTP 204 NO CONTENT: - Simple acknowledgement confirming receipt of the notification and approval of the identity verification flow, without returning data for the merchant partner - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints type: object properties: id: $ref: '#/components/schemas/request-id' type: const: NOTIFY_SESSION_FLOW payload: type: object properties: verificationSessionId: $ref: '#/components/schemas/resource-id' description: | The verification session identifier generated by Bango. routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' shared: description: > Current negotiation data shared between the payment provider and the merchant partner type: object properties: nextAction: $ref: '#/components/schemas/nextAction' merchantToPaymentProvider: $ref: '#/components/schemas/merchantToPaymentProvider' required: - merchantToPaymentProvider required: - verificationSessionId - routeConfiguration - shared required: - id - type - payload SEND_MT_MESSAGE: title: SEND_MT_MESSAGE request action (outbound) description: > Ask the payment provider [adapter] to send a message to an end user's device. Typically this is an SMS to a phone number, but this request action does not imply or require a specific transport mechanism. (See also [`SEND_OTP`](/schemas/SEND_OTP), where the Bango Platform asks the payment provider to generate and send a OTP to the end user.) If there's a problem with the request action, the payment provider [adapter] returns HTTP 400. For example, if the payment provider [adapter] doesn't recognize the account properties in the request, it returns HTTP 400. If there's a problem sending the message to the end user, the payment provider [adapter] returns a [`SEND_MT_MESSAGE_RESPONSE`](/schemas/SEND_MT_MESSAGE_RESPONSE) response action including a `status` code. ### Supported HTTP responses - HTTP 200 OK: - [`SEND_MT_MESSAGE_RESPONSE`](/schemas/SEND_MT_MESSAGE_RESPONSE) response action - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints, or - `payload.account` does not identify an end user account known to the payment provider type: object properties: id: $ref: '#/components/schemas/request-id' type: const: SEND_MT_MESSAGE payload: type: object properties: routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' account: $ref: '#/components/schemas/payment-instrument-account-properties' message: description: | The message to send to the end user's device. type: string minLength: 1 maxLength: 600 example: 1234 is your PIN for Aussie Apps required: - routeConfiguration - account - message required: - id - type - payload VALIDATE_PASSPHRASE: title: VALIDATE_PASSPHRASE request action (outbound) description: > Ask the payment provider [adapter] to validate a passphrase for an end user. The end user is authenticated using the passphrase provided to the merchant through the payment provider in the Bango Platform. ### Supported HTTP responses - HTTP 200 OK: - [`VALIDATE_PASSPHRASE_RESPONSE`](/schemas/VALIDATE_PASSPHRASE_RESPONSE) response action - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints - `payload.account` does not identify an end user account known to the payment provider type: object properties: id: $ref: '#/components/schemas/request-id' type: const: VALIDATE_PASSPHRASE payload: type: object properties: routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' account: $ref: '#/components/schemas/payment-instrument-account-properties' description: | Account identification data for the end user. type: object passphrase: description: > the end user's passphrase authentication to be validated by the payment provider. type: string minLength: 1 maxLength: 50 example: Worry3-Troops-Failed-Sang additionalProperties: false required: - routeConfiguration - account - passphrase required: - id - type - payload SEND_OTP: title: SEND_OTP request action (outbound) description: > Ask the payment provider [adapter] to send an OTP to an end user's device. Typically this is an SMS to a phone number, but this request action does not imply or require a specific transport mechanism. The OTP and the message are controlled by the payment provider (contrast with [`SEND_MT_MESSAGE`](/schemas/SEND_MT_MESSAGE), where the Bango Platform owns the OTP and the message). Later, use [`VERIFY_OTP`](/schemas/VERIFY_OTP) to check the end user supplied the correct OTP. If there's a problem with the request action, the payment provider [adapter] returns HTTP 400. For example, if the payment provider [adapter] doesn't recognize the account properties in the request, it returns HTTP 400. If there's a problem sending the message to the end user, the payment provider [adapter] returns a [`SEND_OTP_RESPONSE`](/schemas/SEND_OTP_RESPONSE) response action including a `status` code. ### Supported HTTP responses - HTTP 200 OK: - [`SEND_OTP_RESPONSE`](/schemas/SEND_OTP_RESPONSE) response action - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints, or - `payload.account` does not identify an end user account known to the payment provider type: object properties: id: $ref: '#/components/schemas/request-id' type: const: SEND_OTP payload: type: object properties: routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' account: $ref: '#/components/schemas/payment-instrument-account-properties' otpAction: $ref: '#/components/schemas/payment-provider-otpAction' required: - routeConfiguration - account - otpAction required: - id - type - payload VERIFY_OTP: title: VERIFY_OTP request action (outbound) description: > Ask the payment provider [adapter] to verify an OTP provided by the merchant end user. Used only when the payment provider manages OTPs, and after sending [`SEND_OTP`](/schemas/SEND_OTP). If there's a problem with the request action, the payment provider [adapter] returns HTTP 400. For example, if the payment provider [adapter] doesn't recognize the account properties in the request, it returns HTTP 400. If there's a problem verifying the OTP, the payment provider [adapter] returns a [`VERIFY_OTP_RESPONSE`](/schemas/VERIFY_OTP_RESPONSE) response action including a `status` code. ### Supported HTTP responses - HTTP 200 OK: - [`VERIFY_OTP_RESPONSE`](/schemas/VERIFY_OTP_RESPONSE) response action - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request action - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints, or - `payload.account` does not identify an end user account known to the payment provider type: object properties: id: $ref: '#/components/schemas/request-id' type: const: VERIFY_OTP payload: type: object properties: routeConfiguration: $ref: '#/components/schemas/payment-route-configuration-properties' account: $ref: '#/components/schemas/payment-instrument-account-properties' candidate: description: | The end user's candidate OTP. type: string minLength: 1 maxLength: 100 required: - routeConfiguration - account - candidate required: - id - type - payload GET_ELIGIBILITY_RESPONSE: title: GET_ELIGIBILITY_RESPONSE response action description: > Response to a `GET_ELIGIBILITY` action. Contains information about the current eligibility of an end user. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: GET_ELIGIBILITY_RESPONSE payload: type: object properties: paymentEligibilityStatus: $ref: '#/components/schemas/paymentEligibilityStatus' paymentInstrumentProperties: $ref: >- #/components/schemas/payment-instrument-properties-without-account required: - paymentEligibilityStatus required: - id - type - payload AUTHORIZE_APPROVED_RESPONSE: title: AUTHORIZE_APPROVED_RESPONSE response action description: > Notification that a request to the payment provider [adapter] to authorize a payment (step 1 of two-step payments) has succeeded. (Denials use the `AUTHORIZE_DENIED_RESPONSE` response action.) A payment provider [adapter] may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The merchant partner sees this ID in the payment resource. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: AUTHORIZE_APPROVED_RESPONSE payload: type: object properties: paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' shared: $ref: '#/components/schemas/payment-provider-shared' required: - id - type - payload AUTHORIZE_DENIED_RESPONSE: title: AUTHORIZE_DENIED_RESPONSE response action description: > Notification that a request to the payment provider [adapter] to authorize a payment (step 1 of two-step payments) has been denied. A payment provider [adapter] includes a `code` and optionally a `message` property with more details. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: AUTHORIZE_DENIED_RESPONSE payload: type: object properties: code: description: > A machine-readable code that indicates why the payment provider denied authorization. **NOTE** This is a provisional list of values for `code` type: string enum: - operation-not-supported - denied - user-invalid - user-barred - user-suspended - user-not-enabled - user-insufficient-credit - user-spend-limit-exceeded - already-in-progress - payment-unknown message: description: > An optional human-readable message describing why the payment provider denied authorization. type: string minLength: 1 maxLength: 255 paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' required: - code required: - id - type - payload CANCEL_AUTH_APPROVED_RESPONSE: title: CANCEL_AUTH_APPROVED_RESPONSE response action description: > Confirmation that a request to the payment provider [adapter] to cancel authorization for a payment has succeeded. (Denials use the `CANCEL_AUTH_DENIED_RESPONSE` response action.) A payment provider [adapter] may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The merchant partner sees this ID in the payment resource. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: CANCEL_AUTH_APPROVED_RESPONSE payload: type: object properties: paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' required: - id - type - payload CANCEL_AUTH_DENIED_RESPONSE: title: CANCEL_AUTH_DENIED_RESPONSE response action description: > Notification that a request to the payment provider [adapter] to cancel authorization for a payment has been denied. A payment provider [adapter] includes a `code` and optionally a `message` property with more details. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: CANCEL_AUTH_DENIED_RESPONSE payload: type: object properties: code: description: > A machine-readable code that indicates why the payment provider denied the cancelation request. **NOTE** This is a provisional list of values for `code` type: string enum: - operation-not-supported - denied - expired - user-invalid - user-barred - user-suspended - user-not-enabled - already-in-progress - payment-unknown message: description: > An optional human-readable message describing why the payment provider denied the cancelation request. type: string minLength: 1 maxLength: 255 paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' required: - code required: - id - type - payload CAPTURE_APPROVED_RESPONSE: title: CAPTURE_APPROVED_RESPONSE response action description: > Confirmation that a request to the payment provider [adapter] to capture a payment (step 2 of two-step payments) has succeeded. (Denials use the `CAPTURE_DENIED_RESPONSE` response action.) A payment provider [adapter] may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The merchant partner sees this ID in the payment resource. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: CAPTURE_APPROVED_RESPONSE payload: type: object properties: paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' required: - id - type - payload CAPTURE_DENIED_RESPONSE: title: CAPTURE_DENIED_RESPONSE response action description: > Notification that a request to the payment provider [adapter] to capture a payment (step 2 of two-step payments) has been denied. A payment provider [adapter] includes a `code` and optionally a `message` property with more details. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: CAPTURE_DENIED_RESPONSE payload: type: object properties: code: description: > A machine-readable code that indicates why the payment provider denied capture. **NOTE** This is a provisional list of values for `code` type: string enum: - operation-not-supported - denied - expired - user-invalid - user-barred - user-suspended - user-not-enabled - user-insufficient-credit - user-spend-limit-exceeded - already-in-progress - payment-unknown message: description: > An optional human-readable message describing why the payment provider denied capture. type: string minLength: 1 maxLength: 255 paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' required: - code required: - id - type - payload CHARGE_APPROVED_RESPONSE: title: CHARGE_APPROVED_RESPONSE response action [plan-p1] description: > Confirmation that a request to the payment provider [adapter] to charge a payment (one-step payments) has succeeded. (Denials use the `CHARGE_DENIED_RESPONSE` response action.) A payment provider [adapter] may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The merchant partner DOES NOT see this ID. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: CHARGE_APPROVED_RESPONSE payload: type: object properties: paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' required: - id - type - payload CHARGE_DENIED_RESPONSE: title: CHARGE_DENIED_RESPONSE response action [plan-p1] description: > Notification that a request to the payment provider [adapter] to charge a payment (one-step payments) has been denied. A payment provider [adapter] includes a `code` and optionally a `message` property with more details. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: CHARGE_DENIED_RESPONSE payload: type: object properties: code: description: > A machine-readable code that indicates why the payment provider denied the charge. **NOTE** This is a provisional list of values for `code` type: string enum: - operation-not-supported - denied - user-invalid - user-barred - user-suspended - user-not-enabled - user-insufficient-credit - user-spend-limit-exceeded - already-in-progress - payment-unknown message: description: > An optional human-readable message describing why the payment provider denied the charge. type: string minLength: 1 maxLength: 255 paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' required: - code required: - id - type - payload REFUND_APPROVED_RESPONSE: title: REFUND_APPROVED_RESPONSE response action description: > Confirmation that a request to the payment provider [adapter] to refund a payment has succeeded. (Denials use the `REFUND_DENIED_RESPONSE` response action.) A payment provider [adapter] may include a `paymentProviderPaymentId` property to supply the Bango Platform with its own unique identifier for the payment. The merchant partner sees this ID in the payment resource. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: REFUND_APPROVED_RESPONSE payload: type: object properties: paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' required: - id - type - payload REFUND_DENIED_RESPONSE: title: REFUND_DENIED_RESPONSE response action description: > Notification that a request to the payment provider [adapter] to refund a payment has been denied. A payment provider [adapter] includes a `code` and optionally a `message` property with more details. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: REFUND_DENIED_RESPONSE payload: type: object properties: code: description: > A machine-readable code that indicates why the payment provider denied the refund. **NOTE** This is a provisional list of values for `code` type: string enum: - operation-not-supported - denied - expired - user-invalid - user-barred - user-suspended - user-not-enabled - already-in-progress - payment-unknown message: description: > An optional human-readable message describing why the payment provider denied the refund. type: string minLength: 1 maxLength: 255 paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' required: - code required: - id - type - payload NOTIFY_SESSION_FLOW_APPROVED_RESPONSE: title: NOTIFY_SESSION_FLOW_APPROVED_RESPONSE response action description: > Response to a `NOTIFY_SESSION_FLOW` request action. Confirmation that the merchant may start the requested identity verification flow, optionally including data to return to the merchant, and optionally initializing payment instrument properties. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: NOTIFY_SESSION_FLOW_APPROVED_RESPONSE payload: type: object properties: paymentInstrumentProperties: $ref: '#/components/schemas/payment-instrument-properties-partial-patch' shared: description: > The negotiation data shared from the payment provider to the merchant partner type: object properties: nextAction: $ref: '#/components/schemas/nextAction' paymentProviderToMerchant: $ref: '#/components/schemas/paymentProviderToMerchant' required: - id - type - payload NOTIFY_SESSION_FLOW_DENIED_RESPONSE: title: NOTIFY_SESSION_FLOW_DENIED_RESPONSE response action description: > Denial of a merchant partner request to start an identity verification flow. A payment provider [adapter] includes a `code` and optionally a `message` property with more details. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: NOTIFY_SESSION_FLOW_DENIED_RESPONSE payload: type: object properties: code: description: > A machine-readable code that indicates why the payment provider denied the identity verification flow. **NOTE** This is a provisional list of values for `code` type: string enum: - operation-not-supported - denied message: description: > An optional human-readable message describing why the payment provider denied the identity verification flow. type: string minLength: 1 maxLength: 255 required: - code required: - id - type - payload SEND_MT_MESSAGE_RESPONSE: title: SEND_MT_MESSAGE_RESPONSE response action description: > Response to a `SEND_MT_MESSAGE` action. Identifies whether or not the payment provider [adapter] was able to send the message to the end user. Note that if the payment provider [adapter] did not recognize the account properties in the request, it returns HTTP 400 for the `SEND_MT_MESSAGE` request action, and not a `SEND_MT_MESSAGE_RESPONSE` response action. If the status is `send-request-failure` or `unknown`, this may be reported to the merchant as a `payment-provider-failure` error with `paymentProviderCode` set to `mt-message-send-request-failure`. If the status is `send-requested`, this DOES NOT guarantee the message was delivered. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: SEND_MT_MESSAGE_RESPONSE payload: type: object properties: status: description: > The outcome of the payment provider [adapter] attempt to send the message to the end user. Possible values: - `send-requested`: Request to send the message was accepted. This DOES NOT guarantee the message was delivered - `send-request-failure`: Request to send the message was not accepted, and no detailed explanation is available - `unknown`: No information is available to indicate whether the message was sent Additional `status` values will be added as needed. type: string enum: - send-requested - send-request-failure - unknown required: - status required: - id - type - payload VALIDATE_PASSPHRASE_RESPONSE: title: VALIDATE_PASSPHRASE_RESPONSE response action description: > Response to a `VALIDATE_PASSPHRASE` action. Contains information about the validity of the passphrase provided by the end user. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: VALIDATE_PASSPHRASE_RESPONSE payload: type: object properties: status: $ref: '#/components/schemas/passphrase-status' required: - status required: - id - type - payload SEND_OTP_RESPONSE: title: SEND_OTP_RESPONSE response action description: > Response to a `SEND_OTP` action. Identifies whether or not the payment provider [adapter] was able to (perhaps generate and) send the OTP to the end user. Note that if the payment provider [adapter] did not recognize the account properties in the request, it returns HTTP 400 for the `SEND_OTP` request action, and not a `SEND_OTP_RESPONSE` response action. If the status is `send-request-failure` or `unknown`, this may be reported to the merchant as a `payment-provider-failure` error with `paymentProviderCode` set to `otp-request-failure`. If the status is `send-requested`, this DOES NOT guarantee the message was delivered. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: SEND_OTP_RESPONSE payload: type: object properties: status: description: > The outcome of the payment provider [adapter] attempt to send the OTP to the end user. Possible values: - `send-requested`: Request to send the OTP was accepted. This DOES NOT guarantee the message was delivered - `send-request-denied`: Request to send the OTP was denied for security reasons - `send-request-failure`: Request to send the OTP was not accepted, and no detailed explanation is available - `unknown`: No information is available to indicate whether the OTP was sent Additional `status` values will be added as needed. type: string enum: - send-requested - send-request-denied - send-request-failure - unknown required: - status required: - id - type - payload VERIFY_OTP_RESPONSE: title: VERIFY_OTP_RESPONSE response action description: > Response to a `VERIFY_OTP` action. Identifies whether or not the payment provider [adapter] was able to verify the OTP supplied by the end user, and whether the candidate OTP from the end user was the expected OTP. Note that if the payment provider [adapter] did not recognize the account properties in the request, it returns HTTP 400 for the `VERIFY_OTP` request action, and not a `VERIFY_OTP_RESPONSE` response action. If the status is `unknown`, this may be reported to the merchant as a `payment-provider-failure` error with `paymentProviderCode` set to `otp-request-failure`. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: VERIFY_OTP_RESPONSE payload: type: object properties: status: description: > The outcome of the payment provider [adapter] attempt to verify the OTP. Possible values: - `otp-correct`: The candidate OTP from the end user was the expected OTP - `otp-incorrect`: The candidate OTP from the end user was not the expected OTP - `otp-expired`: The candidate OTP was not checked because the OTP has expired - `too-many-attempts`: The candidate OTP was not checked because the maximum number of attempts has been reached - `unknown`: No information is available to indicate whether the OTP was verified Additional `status` values will be added as needed. type: string enum: - otp-correct - otp-incorrect - otp-expired - too-many-attempts - unknown paymentInstrumentProperties: $ref: >- #/components/schemas/payment-instrument-properties-account-required required: - status - paymentInstrumentProperties required: - id - type - payload payment-provider-internal-server-error: title: internal-server-error [PP] description: Internal server error type: object properties: code: const: internal-server-error meta: description: Additional information to help identify the specific error case type: object properties: canRetry: description: Whether the payment provider believes the request can be retried type: boolean default: false message: description: Human-readable message describing the error type: string example: >- The server encountered an unexpected condition which prevented it from fulfilling the request url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/internal-server-error required: - code - meta - message adapter-failure: title: adapter-failure description: Bango adapter failed type: object properties: code: const: adapter-failure meta: description: Additional information to help identify the specific error case type: object properties: canRetry: description: Whether the request can be retried type: boolean default: true message: description: Human-readable message describing the error type: string example: >- The Bango adapter encountered an unexpected condition which prevented it from fulfilling the request url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/adapter-failure required: - code - meta - message request-id: title: Unique identifier for request action description: > A unique identifier for the request action (not used for any other purpose). If the recipient of the request action returns a response action, the response action must specify the same identifier as its own `id`. type: string format: uuid example: 2adf1639-bb50-4df7-b8a0-79a0cd4f2277 payment-route-configuration-properties: title: Billing route properties description: | Properties of a billing route type: object properties: authentication: $ref: '#/components/schemas/adapter-authentication-properties' paymentProviderId: $ref: '#/components/schemas/payment-provider-id' merchantId: $ref: '#/components/schemas/merchant-id' routingKey: x-bango-public-description: | Routing key description: | ???? type: string countryCode: $ref: '#/components/schemas/country-code-iso-3166' required: - paymentProviderId - merchantId example: authentication: type: OAuth endpoint: https://oauth.customer.com paymentProviderId: OGNABTEL merchantId: OGNAB_PLUS routingKey: '12345' countryCode: MX payment-authorize-request-properties: title: Authorize payment request properties description: | Authorize payment request properties type: object properties: bangoPaymentId: $ref: '#/components/schemas/bango-payment-id' merchantPaymentId: $ref: '#/components/schemas/merchant-payment-id' merchantRequestId: $ref: '#/components/schemas/merchant-request-id' actionAmount: allOf: - $ref: '#/components/schemas/monetary-value-required' - description: | The amount and currency of the Authorize request balance: $ref: '#/components/schemas/payment-balance' saleItem: $ref: '#/components/schemas/sale-item' shared: $ref: '#/components/schemas/payment-shared' required: - bangoPaymentId - actionAmount - balance - saleItem - shared example: bangoPaymentId: 926f51a4-d992-4bf2-ab57-577007098880 merchantPaymentId: '12343567' merchantRequestId: asldjfaklsdhfalskjhfd actionAmount: amount: 999 currency: USD balance: authorized: amount: 0 currency: USD captured: amount: 0 currency: USD refunded: amount: 0 currency: USD canceled: amount: 0 currency: USD saleItem: description: Bango Music - 1 Month Subscription category: DIGITAL_GOODS price: amount: 999 currency: USD shared: merchantToPaymentProvider: recombobulationId: abcd payment-instrument-properties: title: Payment instrument properties description: | Payment instrument properties, including: - Account identifiers - Properties that apply universally across all merchants - Properties that apply for specific merchants type: object additionalProperties: false properties: account: $ref: '#/components/schemas/payment-instrument-account-properties' global: $ref: '#/components/schemas/payment-instrument-global-properties' route: title: Per-route properties, indexed by friendly merchant ID description: > Property names are friendly string identifiers for merchant partners (for example, `OGNAB_PLUS`). Each string maps to a partner namespace ID in the shared route-config-service. type: object properties: SOME_MERCHANT_ID: $ref: '#/components/schemas/payment-instrument-route-properties' locale-bcp-47: title: BCP 47 language tag description: > A [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag. type: string minLength: 1 maxLength: 50 examples: - en-US - ar-SA idempotency: title: Idempotency properties description: > Properties related to idempotency, to help with reconciliation between the Bango Platform and the payment provider. Omitted if the merchant partner did not specify an `Idempotency-Key` with the request. type: object properties: operationId: description: > A unique, random identifier for the operation. The same `operationId` is reused if the operation is retried. type: string format: uuid paymentProviderOperationId: description: > An optional identifier used by the payment provider to identify retries. Used where the payment provider is unable to accept Bango's operationId. type: string minLength: 1 maxLength: 255 isRetry: description: > Whether this request is a retry of an earlier request with the same `operationId`. type: boolean required: - operationId - isRetry example: operationId: d69113a4-e631-43f5-b054-2567467bbbf7 paymentProviderOperationId: Jv290FSkm34guhSODUFmvksdfh isRetry: false payment-cancel-auth-request-properties: title: Cancel Authorize payment request properties description: | Cancel Authorize payment request properties type: object properties: bangoPaymentId: $ref: '#/components/schemas/bango-payment-id' merchantPaymentId: $ref: '#/components/schemas/merchant-payment-id' merchantRequestId: $ref: '#/components/schemas/merchant-request-id' actionAmount: allOf: - $ref: '#/components/schemas/monetary-value-required' - description: | The amount and currency of the cancel authorization request paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' balance: $ref: '#/components/schemas/payment-balance' saleItem: $ref: '#/components/schemas/sale-item' shared: $ref: '#/components/schemas/payment-shared' required: - bangoPaymentId - actionAmount - balance - saleItem - shared example: bangoPaymentId: 926f51a4-d992-4bf2-ab57-577007098880 merchantPaymentId: '12343567' merchantRequestId: asldjfaklsdhfalskjhfd actionAmount: amount: 450 currency: USD paymentProviderPaymentId: '1231232' balance: authorized: amount: 999 currency: USD captured: amount: 0 currency: USD refunded: amount: 0 currency: USD canceled: amount: 0 currency: USD saleItem: description: Bango Music - 1 Month Subscription category: DIGITAL_GOODS price: amount: 999 currency: USD shared: merchantToPaymentProvider: recombobulationId: abcd payment-capture-request-properties: title: Capture payment request properties description: | Capture payment request properties type: object properties: bangoPaymentId: $ref: '#/components/schemas/bango-payment-id' merchantPaymentId: $ref: '#/components/schemas/merchant-payment-id' merchantRequestId: $ref: '#/components/schemas/merchant-request-id' paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' actionAmount: allOf: - $ref: '#/components/schemas/monetary-value-required' - description: | The amount and currency of the Capture request balance: $ref: '#/components/schemas/payment-balance' saleItem: $ref: '#/components/schemas/sale-item' shared: $ref: '#/components/schemas/payment-shared' required: - bangoPaymentId - actionAmount - balance - saleItem - shared example: bangoPaymentId: 926f51a4-d992-4bf2-ab57-577007098880 merchantPaymentId: '12343567' merchantRequestId: asldjfaklsdhfalskjhfd paymentProviderPaymentId: 3ee9a989-24c8-4d66-b470-87297711c148 actionAmount: amount: 450 currency: USD balance: authorized: amount: 450 currency: USD captured: amount: 0 currency: USD refunded: amount: 0 currency: USD canceled: amount: 0 currency: USD saleItem: description: Bango Music - 1 Month Subscription category: DIGITAL_GOODS price: amount: 450 currency: USD shared: merchantToPaymentProvider: recombobulationId: abcd payment-charge-request-properties: title: Charge payment request properties description: | Charge payment request properties type: object properties: bangoPaymentId: $ref: '#/components/schemas/bango-payment-id' merchantPaymentId: $ref: '#/components/schemas/merchant-payment-id' merchantRequestId: $ref: '#/components/schemas/merchant-request-id' actionAmount: allOf: - $ref: '#/components/schemas/monetary-value-required' - description: | The amount and currency of the Charge request balance: $ref: '#/components/schemas/payment-balance' saleItem: $ref: '#/components/schemas/sale-item' shared: $ref: '#/components/schemas/payment-shared' required: - bangoPaymentId - actionAmount - balance - saleItem - shared example: bangoPaymentId: 926f51a4-d992-4bf2-ab57-577007098880 merchantPaymentId: '12343567' merchantRequestId: asldjfaklsdhfalskjhfd actionAmount: amount: 999 currency: USD balance: authorized: amount: 0 currency: USD captured: amount: 0 currency: USD refunded: amount: 0 currency: USD canceled: amount: 0 currency: USD saleItem: description: Bango Music - 1 Month Subscription category: DIGITAL_GOODS price: amount: 999 currency: USD shared: merchantToPaymentProvider: recombobulationId: abcd payment-refund-request-properties: title: Refund payment request properties description: | Refund payment request properties type: object properties: bangoPaymentId: $ref: '#/components/schemas/bango-payment-id' merchantPaymentId: $ref: '#/components/schemas/merchant-payment-id' merchantRequestId: $ref: '#/components/schemas/merchant-request-id' paymentProviderPaymentId: $ref: '#/components/schemas/payment-provider-payment-id' actionAmount: allOf: - $ref: '#/components/schemas/monetary-value-required' - description: | The amount and currency of the Refund request balance: $ref: '#/components/schemas/payment-balance' saleItem: $ref: '#/components/schemas/sale-item' shared: $ref: '#/components/schemas/payment-shared' required: - bangoPaymentId - actionAmount - balance - saleItem - shared example: bangoPaymentId: 926f51a4-d992-4bf2-ab57-577007098880 merchantPaymentId: '12343567' merchantRequestId: asldjfaklsdhfalskjhfd paymentProviderPaymentId: '1231232' actionAmount: amount: 450 currency: USD balance: authorized: amount: 999 currency: USD captured: amount: 999 currency: USD refunded: amount: 0 currency: USD canceled: amount: 0 currency: USD saleItem: description: Bango Music - 1 Month Subscription category: DIGITAL_GOODS price: amount: 999 currency: USD shared: merchantToPaymentProvider: recombobulationId: abcd payment-instrument-account-properties: title: Payment instrument account properties description: > Properties of a payment instrument that identify the account with the payment provider. In many cases, this is a phone number. MUST contain at least one property. MAY contain more than one property. All property values MUST be strings. The `phoneNumber` property defined here MUST be used IF the payment provider identifies the account using a phone number that can be expressed in E.164 format with a leading `+`. Otherwise, the property MUST NOT be used (use a property with a different name instead). type: object minProperties: 1 maxProperties: 50 unevaluatedProperties: type: string minLength: 1 maxLength: 512 properties: phoneNumber: $ref: '#/components/schemas/phone-number' example: phoneNumber: '+447700900123' anyPropertyNeededByThePaymentProvider: some-string resource-id: title: Resource ID description: > 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. type: string format: uuid example: 581b2e40-741c-4683-ae66-46c9fe6f4d5e nextAction: description: > An optional next action for either the merchant partner or the payment provider. This string, read/write for both parties, allows either party to send an explicit signal to the other using a well-defined property. Either party may set the string as part of an "update shared data" operation. Typically the string is used by one party to inform the other party that there is session data for them to process to progress the negotation. That session data should provide additional context as needed. For flexibility, this schema specifies any string. Bango recommends using these strings: - `none`: No next action is currently defined - `merchant`: A signal for the merchant partner to take the next action - `payment-provider`: A signal for the payment provider to take the next action type: string minLength: 1 default: none merchantToPaymentProvider: description: > Data the merchant partner owns (read/write access) and the payment provider may consume (read access only). This specification defines some properties that merchant partners and payment providers MAY use for certain purposes. These properties are optional, but if specified MUST match the schemas defined here. Merchant partners and payment providers MAY use other properties not defined here. type: object properties: authSuccessRedirectUrl: description: > The merchant URL to which the payment provider should redirect the end user after a successful authentication. type: string format: url example: https://example.com/merchant/user-login-ok authFailureRedirectUrl: description: > The merchant URL to which the payment provider should redirect the end user after a failed authentication. type: string format: url example: https://example.com/merchant/user-login-failed payment-provider-otpAction: title: Payment provider OTP Action description: | The OTP action for the SEND_OTP operation. type: string enum: - reset - resend - send response-id: title: Unique request identifier description: > The unique identifier for the request action to which this is a response. type: string format: uuid example: 2adf1639-bb50-4df7-b8a0-79a0cd4f2277 paymentEligibilityStatus: description: > Whether the account identification data in the request may be used to process payments. - `enabled`: Authorized partners can use the account data to process payments - `not-enabled`: Authorized partners cannot use the account data to process payments - `closed`: The payment provider has closed the account and it can no longer process payments - `barred`: The payment provider has suspended or barred the user associated with the account (this may be temporary) - `unknown`: The payment provider has not provided information about this account - `unsupported`: The payment provider does not support requests for information about this account type: string enum: - enabled - not-enabled - closed - barred - unknown - unsupported example: enabled payment-instrument-properties-without-account: title: Payment instrument properties description: | Payment instrument properties, including: - Properties that apply universally across all merchants - Properties that apply for specific merchants type: object additionalProperties: false properties: global: $ref: '#/components/schemas/payment-instrument-global-properties-oppa' route: title: Per-route properties, indexed by friendly merchant ID description: > Property names are friendly string identifiers for merchant partners (for example, `OGNAB_PLUS`). Each string maps to a partner namespace ID in the shared route-config-service. type: object properties: SOME_MERCHANT_ID: $ref: '#/components/schemas/payment-instrument-route-properties' payment-provider-payment-id: title: Payment provider payment ID description: > 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. type: string minLength: 1 maxLength: 255 example: 345hkjhsgdkfgh43k5hjkhk1 payment-provider-shared: title: Data shared between payment provider and merchant description: > Data shared between the payment provider and the merchant partner as part of a payment resource. Supplied to the merchant with a successful `AUTHORIZE` action response. type: object properties: paymentProviderToMerchant: description: > Data the payment provider owns (read/write access) and the merchant partner may consume (read access only). Constraints: - Between 0 and 255 properties - Each property value is either: - string (length 0 to 255 inclusive) - number (-1048575 to +1048575 inclusive) - boolean - array (between 0 and 255 items) containing a mixture of: - string (length 0 to 255 inclusive) - number (-1048575 to +1048575 inclusive) Note that nested objects ARE NOT permitted. type: object maxProperties: 255 additionalProperties: oneOf: - type: string minLength: 0 maxLength: 255 - type: number minimum: -1048575 maximum: 1048575 - type: boolean - type: array maxItems: 255 items: oneOf: - type: string minLength: 0 maxLength: 255 - type: number minimum: -1048575 maximum: 1048575 - type: boolean payment-instrument-properties-partial-patch: title: Payment instrument properties partial patch object description: > A **partial** patch object for payment instrument properties. A payment provider [adapter] can specify: - Properties to merge (add, update) with the existing account properties - Properties to patch (add, update, or remove) the existing global properties that apply universally across all merchants - Properties to patch (add, update, or remove) the existing merchant-specific properties type: object properties: account: title: Account identification properties description: > Merge (add, update) properties that identify the account with the payment provider. Requests can specify any additional string properties needed by the payment provider to identify the account. allOf: - $ref: '#/components/schemas/payment-instrument-account-properties' global: $ref: '#/components/schemas/payment-instrument-global-properties-patch' route: title: Per-route properties, indexed by friendly merchant ID description: > Patch (add, update, or remove) properties that apply per-merchant. Property names are friendly string identifiers for merchant partners (for example, `OGNAB_PLUS`). Each string maps to a partner namespace ID in the shared route-config-service. allOf: - $ref: '#/components/schemas/simple-object-patch' type: object properties: SOME_MERCHANT_ID: title: Any valid merchant IDs (mapping to partner namespace IDs) description: >- Patch (add, update, or remove) one or more merchant-specific configuration properties. allOf: - $ref: >- #/components/schemas/payment-instrument-route-properties-patch example: account: phoneNumber: '+447700900123' route: OGNAB_PLUS: paymentEligibilityStatus: enabled $remove: - OGNAB_MINUS paymentProviderToMerchant: description: > Data the payment provider owns (read/write access) and the merchant partner may consue (read access only) type: object properties: authRedirectUrl: description: > The payment provider URL to which the merchant should redirect the end user to authenticate to the payment provider. type: string format: url example: https://example.com/payment-provider/login passphrase-status: title: passphrase-Status description: > The status of the passphrase validation as returned by the payment provider Possible values: - `accepted`: The passphrase provided by the user was accepted by the payment provider - `declined`: The passphrase provided by the user was declined by the payment provider - `closed`: The passphrase provided by the user was closed by the payment provider - `barred`: The passphrase provided by the user was barred by the payment provider - `not-enabled`: The passphrase provided by the user was not-enable by the payment provider - `unknown`: An error of some kind occurred requesting the validation of the user passphrase to the payment provider type: string enum: - accepted - declined - closed - barred - not-enabled - unknown examples: - accepted payment-instrument-properties-account-required: title: Payment instrument properties description: | Payment instrument properties, including: - Account identifiers - Properties that apply universally across all merchants - Properties that apply for specific merchants type: object additionalProperties: false properties: account: $ref: '#/components/schemas/payment-instrument-account-properties' global: $ref: '#/components/schemas/payment-instrument-global-properties' route: title: Per-route properties, indexed by friendly merchant ID description: > Property names are friendly string identifiers for merchant partners (for example, `OGNAB_PLUS`). Each string maps to a partner namespace ID in the shared route-config-service. type: object properties: SOME_MERCHANT_ID: $ref: '#/components/schemas/payment-instrument-route-properties' required: - account BadRequest: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/invalid-json' - $ref: '#/components/schemas/missing-parameter' - $ref: '#/components/schemas/invalid-parameter' InvalidCredentials: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/invalid-credentials' PermissionDenied: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/permission-denied' TooManyRequests: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/too-many-requests' PaymentProviderBadGateway: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/payment-provider-bad-gateway' PaymentProviderServiceUnavailable: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/payment-provider-service-unavailable' PaymentProviderGatewayTimeout: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/payment-provider-gateway-timeout' adapter-authentication-properties: title: Adapter Authentication properties description: > Properties used by the payment provider adapters to handle the specific authentication requirements of a payment provider. type: object properties: type: description: | The authentication type used by the Payment Provider adapter type: string enum: - OAuth endpoint: description: | The endpoint used to provide any required authentication tokens. type: string payment-provider-id: title: Payment provider ID description: > Friendly unique identifier for the payment provider. Internally, corresponds to the `accountKey` property in the route-config-server's partner_namespaces table. x-bango-public-description: | Friendly unique identifier for the payment provider. type: string example: OGNABTEL minLength: 2 maxLength: 50 merchant-id: title: Merchant ID description: > Friendly unique identifier for the merchant partner. Internally, corresponds to the `accountKey` property in the route-config-server's partner_namespaces table. x-bango-public-description: | Friendly unique identifier for the merchant partner. type: string example: AUSSIE_APPS minLength: 2 maxLength: 50 country-code-iso-3166: title: ISO 3166-1 alpha-2 country code description: > A two-character [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code. type: string enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW bango-payment-id: title: Bango payment ID allOf: - $ref: '#/components/schemas/resource-id' - description: > Bango's unique identifier for the payment. Copied from the payment resource `rid` property. merchant-payment-id: title: Merchant payment ID description: > The merchant partner's own unique identifier for the payment. Not necessarily a UUID. Uniquely identifies a payment resource (equivalent to the payment resource `rid`). Copied from the payment resource `partnerPaymentId` property. type: string minLength: 1 maxLength: 255 example: asdfg-asdfhj-fgrewa-bcczx merchant-request-id: title: Merchant request ID description: > 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`. type: string minLength: 1 maxLength: 255 example: zfknveriuouzxcqweff12tgdvxxzb0 monetary-value-required: allOf: - $ref: '#/components/schemas/monetary-value' - required: - amount - currency payment-balance: title: Payment balance description: > The total amounts currently authorized, captured, refunded, and canceled for the payment, taking all successful actions into account. For one-step payments, the `authorized` and `captured` values are always identical. type: object properties: authorized: $ref: '#/components/schemas/monetary-value-required' captured: $ref: '#/components/schemas/monetary-value-required' refunded: $ref: '#/components/schemas/monetary-value-required' canceled: $ref: '#/components/schemas/monetary-value-required' required: - authorized - captured - refunded - canceled sale-item: title: Sale item description: | An item (product or service) purchased in whole or part by a payment. type: object properties: description: description: | A description for the item. type: string minLength: 1 maxLength: 255 example: Ognab Music - 6-month subscription category: description: | An optional category for the item. type: string minLength: 1 maxLength: 255 uniqueId: description: > The partner's own unique identifier for the item. Ideally globally unique (a UUID). type: string minLength: 1 maxLength: 255 example: 18c32e64-04dc-4886-83f1-1a7d7ac1a95b price: allOf: - $ref: '#/components/schemas/monetary-value-required' - title: | The full payment expected for this item. required: - description - price payment-shared: title: Data shared between merchant and payment provider description: > 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`. type: object properties: merchantToPaymentProvider: description: > Data the merchant partner owns (read/write access) and the payment provider may consume (read access only). Constraints: - Between 0 and 255 properties - Each property value is either: - string (length 0 to 255 inclusive) - number (-1048575 to +1048575 inclusive) - boolean - array (between 0 and 255 items) containing a mixture of: - string (length 0 to 255 inclusive) - number (-1048575 to +1048575 inclusive) Note that nested objects ARE NOT permitted. type: object maxProperties: 255 additionalProperties: oneOf: - type: string minLength: 0 maxLength: 255 - type: number minimum: -1048575 maximum: 1048575 - type: boolean - type: array maxItems: 255 items: oneOf: - type: string minLength: 0 maxLength: 255 - type: number minimum: -1048575 maximum: 1048575 - type: boolean payment-instrument-global-properties: title: Payment instrument global properties description: > Properties of a payment instrument that apply universally across all merchants. type: object minProperties: 0 maxProperties: 50 unevaluatedProperties: type: string minLength: 1 maxLength: 512 properties: accountType: $ref: '#/components/schemas/payment-provider-account-type' countryCode: $ref: '#/components/schemas/country-code-iso-3166' locale: $ref: '#/components/schemas/locale-bcp-47' currency: $ref: '#/components/schemas/currency-code-iso-4217' customerProfile: $ref: '#/components/schemas/customerProfile' example: accountType: prepaid countryCode: US locale: en-US currency: USD customerProfile: saver profile payment-instrument-route-properties: title: Payment instrument per-route properties description: | Properties of a payment instrument that apply to a specific route. type: object minProperties: 0 maxProperties: 50 unevaluatedProperties: type: string minLength: 1 maxLength: 512 properties: paymentEligibilityStatus: description: > Whether the account identification data in the request may be used to process payments. - `enabled`: Authorized partners can use the account data to process payments - `not-enabled`: Authorized partners cannot use the account data to process payments - `closed`: The payment provider has closed the account and it can no longer process payments - `barred`: The payment provider has suspended or barred the user associated with the account (this may be temporary) - `unknown`: The payment provider has not provided information about this account - `unsupported`: The payment provider does not support requests for information about this account type: string enum: - enabled - not-enabled - closed - barred - unknown - unsupported example: enabled userProperties: $ref: '#/components/schemas/userProperties' OTHERS: description: Other allowed properties TBD example: paymentEligibilityStatus: barred userProperties: token: myUserToken accountNickname: 457 phone-number: title: Phone number (E.164) description: > A phone number in E.164 format, with a leading `+` sign. No spaces or symbols are permitted. type: string pattern: ^\+[1-9]?[0-9]{7,14}$ example: '+447700900123' payment-instrument-global-properties-oppa: title: Payment instrument global properties description: > Properties of a payment instrument that apply universally across all merchants. type: object minProperties: 0 maxProperties: 50 unevaluatedProperties: type: string minLength: 1 maxLength: 512 properties: accountType: $ref: '#/components/schemas/payment-provider-account-type-oppa' countryCode: $ref: '#/components/schemas/country-code-iso-3166' locale: $ref: '#/components/schemas/locale-bcp-47' currency: $ref: '#/components/schemas/currency-code-iso-4217' customerProfile: $ref: '#/components/schemas/customerProfile' example: accountType: prepaid locale: en-US currency: USD customerProfile: saver payment-instrument-global-properties-patch: title: Payment instrument global properties patch description: > Patch (add, update, or remove) properties that apply across all merchants universally. allOf: - $ref: '#/components/schemas/simple-object-patch' type: object minProperties: 0 maxProperties: 50 unevaluatedProperties: type: string minLength: 1 maxLength: 512 properties: accountType: $ref: '#/components/schemas/payment-provider-account-type' countryCode: $ref: '#/components/schemas/country-code-iso-3166' locale: $ref: '#/components/schemas/locale-bcp-47' currency: $ref: '#/components/schemas/currency-code-iso-4217' customerProfile: $ref: '#/components/schemas/customerProfile' example: accountType: prepaid countryCode: US locale: en-US currency: USD customerProfile: saver profile simple-object-patch: title: Simple object patch mechanism description: > Extend an existing object schema with this schema to enable a simple way to patch an object. The extended schema has two special properties: - $replace: boolean. If present, and if true, then this means "remove all existing properties from the object before applying updates" - $remove: an array of property names. If present, then this means "remove properties with these names from the object before applying updates" This extended schema now lets you define a patch object, which specifies operations to perform on an existing object to make a new object. In the patch object, `$replace` and `$remove` (applied first) remove existing properties from the original object, and other properties update the original object. Nested objects might themselves be extended this way: patches are applied recursively. Examples Imagine a schema ABC defining three optional properties `a`, `b`, and `c` whose values are all strings. Consider this object matching schema ABC: ```json { "a": "xyz", "b": "qwerty", "c": "plplpl" } ``` Extend ABC with this schema (adding `$remove` and `$replace`) to get ABC_Patchable. Here's a patch object matching ABC_Patchable: ```json { "$remove": ["b"], "a": "aaaaaaa" } ``` Applying the patch - combining the original object with the patch object - gives this object: ```json { "a": "aaaaaaa", "c": "plplpl" } ``` - The property `b` was removed (because of `$remove` in the patch object) - The property `a` was updated (because it was specified in the patch object) - The property `c` was unchanged (because it wasn't mentioned in the patch object) Another example of a patch object: ```json { "$replace": true, "b": "bbbbbbb" } ``` The result after patching the original object would be: ```json { "b": "bbbbbbb" } ``` - All existing properties were removed (because `$replace` was set to true in the patch object) - The property `b` was updated (because it was specified in the patch object) Now imagine a schema GH defining two properties `g` and `h`, where the value of `g` is a string and the value of `h` is an object (matching schema XY) with optional properties `x` and `y`, both strings. Consider this object matching schema GH: ```json { "g": "ggg", "h": { "x": "xxx", "y": "yyy" } } ``` Extend both GH and the nested XY schemas with this schema, making GH_Patchable. Here's a patch object matching GH_Patchable: ```json { "$remove": ['g'], "h": { "$replace": true, "x": "aaa" } } ``` The result after patching the object above would be: ```json { "h": { "x": "aaa" } } ``` - The property `g` was removed (because of `$remove` in the patch object) - The properties `x` and `y` were removed (because `$replace` was set to true in the inner patch object) - The property `x` was updated (because it was specifed in the inner patch object) type: object properties: $replace: description: > If true, removes all existing properties from the object before applying any property updates. type: boolean default: false $remove: description: > If present, removes the properties named in the array before applying any property updates. It is NOT an error if an array member references a property that does not exist in the object being patched. It is NOT an error if an array member references a property not defined in the schema of the object being patched. It is NOT an error to include a property in the array and also to update its value. type: array items: type: string payment-instrument-route-properties-patch: title: Payment instrument per-route properties description: | Properties of a payment instrument that apply to a specific route. allOf: - $ref: '#/components/schemas/simple-object-patch' type: object minProperties: 0 maxProperties: 50 unevaluatedProperties: type: string minLength: 1 maxLength: 512 properties: paymentEligibilityStatus: description: > Whether the account identification data in the request may be used to process payments. - `enabled`: Authorized partners can use the account data to process payments - `not-enabled`: Authorized partners cannot use the account data to process payments - `closed`: The payment provider has closed the account and it can no longer process payments - `barred`: The payment provider has suspended or barred the user associated with the account (this may be temporary) - `unknown`: The payment provider has not provided information about this account - `unsupported`: The payment provider does not support requests for information about this account type: string enum: - enabled - not-enabled - closed - barred - unknown - unsupported userProperties: $ref: '#/components/schemas/userProperties' example: paymentEligibilityStatus: barred userProperties: token: myUserToken accountNickname: 457 CommonErrorResponse: type: object required: - errors invalid-json: title: invalid-json description: The request body is not valid JSON type: object properties: code: const: invalid-json meta: description: >- Additional information to help identify the specific error case (empty in this case) type: object message: description: Human-readable message describing the error type: string example: The request body is not valid JSON url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/invalid-json required: - code - meta - message missing-parameter: title: missing-parameter description: A required parameter is missing from the request type: object properties: code: const: missing-parameter meta: description: Additional information to help identify the specific error case type: object properties: param: description: The name of the missing parameter type: string required: - param message: description: Human-readable message describing the error type: string example: A required parameter was missing from the request url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/missing-parameter required: - code - meta - message invalid-parameter: title: invalid-parameter description: A request parameter is invalid type: object properties: code: const: invalid-parameter meta: description: Additional information to help identify the specific error case type: object properties: param: description: The name of the invalid parameter type: string reason: description: >- Optional human-readable information to explain why the parameter is invalid. Code must not rely on the content of this string. type: string example: 'Expected format: YYYY-MM-DD' required: - param message: description: Human-readable message describing the error type: string example: A parameter in the request was not valid url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/invalid-parameter required: - code - meta - message invalid-credentials: title: invalid-credentials description: Authentication error - invalid credentials type: object properties: code: const: invalid-credentials meta: description: >- Additional information to help identify the specific error case (empty in this case) type: object message: description: Human-readable message describing the error type: string example: The supplied credentials are not valid url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/invalid-credentials required: - code - meta - message permission-denied: title: permission-denied description: Authorization error - permission denied type: object properties: code: const: permission-denied meta: description: >- Additional information to help identify the specific error case (empty in this case) type: object message: description: Human-readable message describing the error type: string example: The client is not permitted to perform this operation url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/permission-denied required: - code - meta - message too-many-requests: title: too-many-requests description: Too many requests type: object properties: code: const: too-many-requests meta: description: >- Additional information to help identify the specific error case (empty in this case) type: object message: description: Human-readable message describing the error type: string example: Request limit reached. Please try again later url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/too-many-requests required: - code - meta - message payment-provider-bad-gateway: title: bad-gateway [PP] description: Gateway or proxy is unable to complete your request type: object properties: code: const: bad-gateway meta: description: Additional information to help identify the specific error case type: object properties: canRetry: description: Whether the payment provider believes the request can be retried type: boolean default: true message: description: Human-readable message describing the error type: string example: >- The server was unable to complete your request. Please try again later. url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/service-unavailable required: - code - meta - message payment-provider-service-unavailable: title: service-unavailable [PP] description: Service is unavailable type: object properties: code: const: service-unavailable meta: description: Additional information to help identify the specific error case type: object properties: canRetry: description: Whether the payment provider believes the request can be retried type: boolean default: false message: description: Human-readable message describing the error type: string example: >- The service is undergoing maintenance and is not available. Please try again later url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/service-unavailable required: - code - meta - message payment-provider-gateway-timeout: title: gateway-timeout [PP] description: Service is not responding in time type: object properties: code: const: gateway-timeout meta: description: Additional information to help identify the specific error case type: object properties: canRetry: description: Whether the payment provider believes the request can be retried type: boolean default: true message: description: Human-readable message describing the error type: string example: >- The server was unable to complete your request. Please try again later. url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/service-unavailable required: - code - meta - message monetary-value: title: Monetary value description: > A monetary value, including currency. The `amount` value is represented as an integer in the minor units of the `currency` value, if any. For example: - `amount`: `999` and `currency`: `USD` represents USD 9.99, because USD uses two decimal digits for minor units - `amount`: `123` and `currency`: `JPY` represents JPY 123, because JPY has no minor units The Bango Platform uses [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) as the source of truth for currency codes, including minor units. type: object properties: amount: description: > The numeric value, in minor units of the currency. Always an integer. type: integer example: 999 currency: $ref: '#/components/schemas/currency-code-iso-4217' payment-provider-account-type: title: Payment provider account type description: > The account type allocated by the payment provider for an end user's account. type: string enum: - prepaid - postpaid - unknown currency-code-iso-4217: title: ISO 4217 3-char currency code description: > A three-character [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. The allowed values are: - All current ISO 4217 codes except those for precious metals and bonds - ISO 4217 historical codes withdrawn since 2010 ISO 4217 publication: January 1, 2023 type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYN - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EEK - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UYW - UZS - VED - VEF - VES - VND - VUV - WST - XAF - XCD - XDR - XFU - XOF - XPF - XSU - YER - ZAR - ZMK - ZMW - ZWL example: USD customerProfile: title: spending limit profile description: | Customer’s latest spending limit profile type: string maxLength: 50 example: saver userProperties: title: User specific properties description: | Properties that are specific to a user type: object example: userProperties: token: myUserToken accountNickname: 457 specialProperty: key1: value1 payment-provider-account-type-oppa: title: Payment provider account type description: > The account type allocated by the payment provider for an end user's account. type: string enum: - prepaid - postpaid responses: BadRequestErrorResponse: description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' InvalidCredentialsErrorResponse: description: | Authentication error - invalid credentials content: application/json: schema: $ref: '#/components/schemas/InvalidCredentials' PermissionDeniedErrorResponse: description: > User is not authorized for this operation. This error occurs when you try to perform an operation on a resource, and you have permission to access the resource - but you don't have permission to perform the operation. For example, you may be authorized to `GET` the resource but not update it. (If you try to perform any operation on a resource you're not authorized to access, the API returns a 404 error.) content: application/json: schema: $ref: '#/components/schemas/PermissionDenied' TooManyRequestsErrorResponse: description: > Request limit reached. The request was not processed. This error occurs when you send too many requests in a short period of time. You should pause before sending further requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequests' PaymentProviderBadGatewayErrorResponse: description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/PaymentProviderBadGateway' PaymentProviderServiceUnavailableErrorResponse: description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/PaymentProviderServiceUnavailable' PaymentProviderGatewayTimeoutErrorResponse: description: Gateway Timeout content: application/json: schema: $ref: '#/components/schemas/PaymentProviderGatewayTimeout' securitySchemes: BasicAuth: type: http scheme: basic ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.