> ## 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 Bango Platform ## OpenAPI ````yaml /openapi/current/dcb-payments/payment-provider-to-bango/openapi.yaml post /ns/{nsid}/payment-provider/actions openapi: 3.1.0 info: title: Inbound 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 Inbound Payment Provider API (IPPA) allows authenticated/authorized users to send _actions_ to the Bango Platform. An action represents a request for the Bango Platform to perform an operation, or a request for the Bango Platform to provide some data, or a notification to the Bango Platform. ### Glossary - **payment provider**: 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://api.bango.com description: Production server security: - BasicAuth: [] paths: /ns/{nsid}/payment-provider/actions: post: summary: Send an action to the Bango Platform operationId: send-action-inbound parameters: - $ref: '#/components/parameters/NamespaceId' requestBody: description: > An action initiated by the payment provider, to be processed by the Bango Platform. The following action types are available. See each action type schema for detailed information on purpose and response action types. - `SEND_MERCHANT_MESSAGE`: Ask the Bango Platform to forward a message from the payment provider to a merchant partner - `GET_SESSION`: Ask the Bango Platform for the data stored for a verification session - `CONFIRM_SESSION_IDENTITY`: Notify the Bango Platform that an end user was successfully identified as part of an identity verification flow - `REJECT_SESSION_IDENTITY`: Notify the Bango Platform that an end user was NOT successfully identified as part of an identity verification flow - `CANCEL_PI`: Ask the Bango Platform to permanently cancel a payment instrument and any associated payment instrument tokens - `UPDATE_SESSION`: Ask the Bango Platform to store data with a verification session, including data shared with the merchant partner - `GET_PI`: Ask the Bango Platform for the data stored for a payment instrument - `UPDATE_PI`: Ask the Bango Platform to update the data stored for a payment instrument - `NOTIFY_MO`: Provide the Bango Platform with details of an MO message received by the payment provider required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/SEND_MERCHANT_MESSAGE' - $ref: '#/components/schemas/GET_SESSION' - $ref: '#/components/schemas/CONFIRM_SESSION_IDENTITY' - $ref: '#/components/schemas/REJECT_SESSION_IDENTITY' - $ref: '#/components/schemas/CANCEL_PI' - $ref: '#/components/schemas/UPDATE_SESSION' - $ref: '#/components/schemas/GET_PI' - $ref: '#/components/schemas/UPDATE_PI' - $ref: '#/components/schemas/NOTIFY_MO' responses: '200': description: | The response action, which depends on the request action. content: application/vnd.bango.platform-response-action.v1+json: schema: oneOf: - $ref: '#/components/schemas/SESSION_RESPONSE' - $ref: '#/components/schemas/PI_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' '404': $ref: '#/components/responses/NotFoundErrorResponse' '409': description: > The resource is not in the correct state for the requested operation. content: application/json: schema: type: object properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/pi-already-canceled' - $ref: '#/components/schemas/incompatible-state' required: - errors '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' '503': $ref: '#/components/responses/ServiceUnavailableErrorResponse' components: parameters: NamespaceId: in: path name: nsid required: true schema: $ref: '#/components/schemas/namespace-id' schemas: SEND_MERCHANT_MESSAGE: title: SEND_MERCHANT_MESSAGE request action (inbound) description: > _This action might be replaced in a future phase of work_ This action type lets a payment provider ask the Bango Platform to forward a message intact from the payment provider to a merchant partner. The action identifies the merchant partner using a string ID defined by Bango Support as part of the payment provider's configuration settings (different payment providers may use different strings for the same merchant partner). The action includes the message body and a message type. The Bango Platform uses the message type to select how to forward the message to the merchant partner. For example, some merchant partners may reserve different API endpoints for the delivery of different types of message. Not all merchant partners may support all message types. ### Possible HTTP responses - HTTP 204 NO CONTENT: - the message was successfully sent to 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, or - `payload.recipientId` is not recognized as a merchant partner the payment provider may contact, or - `payload.recipientId` is recognized as a merchant partner but it doesn't support the message type, or - `payload.recipientId` is recognized as a merchant partner but it rejected the message (the error's `meta` object may give a reason) type: object properties: id: $ref: '#/components/schemas/request-id' type: const: SEND_MERCHANT_MESSAGE payload: type: object properties: recipientId: description: > The payment provider's configured string identifier for a merchant partner. type: string minLength: 1 maxLength: 255 messageType: description: > The type of message. The Bango Platform uses this to select how to forward the message to the merchant partner. type: string enum: - FRAUD_NOTIFICATION - REMITTANCE_ACCEPTANCE_NOTIFICATION body: description: | The content to forward to the merchant partner. type: string minLength: 1 maxLength: 4095 required: - recipientId - messageType - body required: - id - type - payload GET_SESSION: title: GET_SESSION request action (inbound) description: > This action type lets a payment provider request the data stored for a verification session in the Bango Platform. The response includes data the payment provider has provided to the merchant, and data the merchant has provided to the payment provider. ### Possible HTTP responses - HTTP 200 OK: - [`SESSION_RESPONSE`](/schemas/SESSION_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 - HTTP 404 NOT FOUND with an error: - `code` == `not-found`: - `payload.verificationSessionId` does not identify a verification session that exists, or - `payload.verificationSessionId` does not identify a verification session the payment provider has access to type: object properties: id: $ref: '#/components/schemas/request-id' type: const: GET_SESSION payload: type: object properties: verificationSessionId: $ref: '#/components/schemas/resource-id' description: > The verification session identifier generated by Bango. Bango provided this to the merchant partner to include in the message from the end user's device. required: - verificationSessionId required: - id - type - payload CONFIRM_SESSION_IDENTITY: title: CONFIRM_SESSION_IDENTITY request action (inbound) description: > This action type lets a payment provider notify the Bango Platform that an end user was successfully identified as part of an identity verification flow. The Bango Platform can then generate the payment instrument token for the merchant partner. The action includes optional account identity information, optional global properties for the end user, and optional route-specific properties for the end user. The action can also include data intended for the merchant. After this action, `UPDATE_SESSION` actions will not be processed and will result in an error. ### Possible HTTP responses - HTTP 200 OK: - [`SESSION_RESPONSE`](/schemas/SESSION_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 - a `payload.paymentInstrumentProperties.route` property is not a merchant partner enabled for the payment provider - `code` == `incompatible-state`: - the current verification session state does not permit identity confirmation from the payment provider - HTTP 404 NOT FOUND with an error: - `code` == `not-found`: - `payload.verificationSessionId` does not identify a verification session that exists, or - `payload.verificationSessionId` does not identify a verification session the payment provider has access to type: object properties: id: $ref: '#/components/schemas/request-id' type: const: CONFIRM_SESSION_IDENTITY payload: type: object properties: verificationSessionId: $ref: '#/components/schemas/resource-id' description: > The verification session identifier generated by Bango. Bango provided this to the merchant partner to include in the message from the end user's device. paymentInstrumentProperties: $ref: '#/components/schemas/payment-instrument-properties-partial-patch' shared: description: > Update to the negotiation data shared from the payment provider to the merchant partner. Data in `paymentProviderToMerchant` is merged into the existing data. type: object properties: nextAction: $ref: '#/components/schemas/nextAction' paymentProviderToMerchant: $ref: '#/components/schemas/paymentProviderToMerchant' required: - verificationSessionId required: - id - type - payload REJECT_SESSION_IDENTITY: title: REJECT_SESSION_IDENTITY request action (inbound) description: > This action type lets a payment provider notify the Bango Platform that an end user was not successfully identified as part of an identity verification flow. The Bango Platform can then report this conclusion back to the merchant partner. The action includes an error code that lets the payment provider provide more detailed information. After this action, `UPDATE_SESSION` actions will not be processed and will result in an error. ### Possible HTTP responses - HTTP 200 OK: - [`SESSION_RESPONSE`](/schemas/SESSION_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 - `code` == `incompatible-state`: - the current verification session state does not permit identity rejection from the payment provider - HTTP 404 NOT FOUND with an error: - `code` == `not-found`: - `payload.verificationSessionId` does not identify a verification session that exists, or - `payload.verificationSessionId` does not identify a verification session the payment provider has access to type: object properties: id: $ref: '#/components/schemas/request-id' type: const: REJECT_SESSION_IDENTITY payload: type: object properties: verificationSessionId: $ref: '#/components/schemas/resource-id' description: > The verification session identifier generated by Bango. Bango provided this to the merchant partner to include in the message from the end user's device. code: description: > A machine-readable code that indicates why the payment provider rejected the identity verification session. The payment provider can use the generic code `rejected` if a more specific code is not available. In this case, it's a good idea to include more details in the `message` field. In most cases, the code is reported to the merchant partner in the session resource, in the `result.reasons` array. But note: - `payment-provider-internal-server-error` and `payment-provider-service-unavailable` are both transformed to `payment-provider-failure`, with the value of `meta.paymentProviderCode` set appropriately and `meta.canRetry` always set to `false` (because the merchant can't retry anything) **NOTE** List subject to change. type: string enum: - user-canceled - user-invalid - user-barred - user-suspended - user-not-enabled - expired - payment-provider-internal-server-error - payment-provider-service-unavailable - adapter-failure - rejected message: description: > An optional human-readable message describing why the payment provider rejected the identity verification session. type: string minLength: 1 maxLength: 255 required: - verificationSessionId - code required: - id - type - payload CANCEL_PI: title: CANCEL_PI request action (inbound) description: > This action type lets a payment provider request to cancel a payment instrument in the Bango Platform. Canceling a payment instrument indirectly cancels all payment instrument tokens associated with that payment instrument. It is not possible to undo cancelation. The action includes account identity information, and an optional reason for the cancelation. This specification defines a set of reason codes: more can be added as needed. ### Possible HTTP responses - HTTP 200 OK: - [`PI_RESPONSE`](/schemas/PI_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 - HTTP 404 NOT FOUND with an error: - `code` == `not-found`: - `payload.account` does not identify a payment instrument that exists, or - `payload.account` does not identify a payment instrument the payment provider has access to - HTTP 409 CONFLICT with error: - `code` == `pi-already-canceled`: - the payment instrument is already canceled type: object properties: id: $ref: '#/components/schemas/request-id' type: const: CANCEL_PI payload: type: object properties: account: $ref: '#/components/schemas/payment-instrument-account-properties' description: | Account identifiers for the payment instrument to cancel. code: description: > An optional reason code, allowing the payment provider to explain why the payment instrument is being canceled. These reason codes have been defined: - `account-closed`: the payment provider account has closed - `other-payment-provider`: the account identifier is not recognized by the payment provider, and may belong to another - `user-not-eligible`: the payment provider account holder is no longer eligible for payment processing - `other`: another reason Other reason codes will be added as required. type: string enum: - account-closed - other-payment-provider - user-not-eligible - other message: description: > An optional human-readable message to further explain why the payment instrument is being canceled. type: string example: Account migrated to another payment provider required: - account required: - id - type - payload UPDATE_SESSION: title: UPDATE_SESSION request action (inbound) description: > This action type lets a payment provider store short-lived or long-lived data about the verification session in the Bango Platform. The Bango Platform can use some or all of this data later (after receiving a `CONFIRM_SESSION_IDENTITY` action) to generate the payment instrument token for the merchant partner. The action includes account identity information, optional global properties for the end user, and optional route-specific properties for the end user. The update can also include data intended for the merchant. ### Possible HTTP responses - HTTP 200 OK: - [`SESSION_RESPONSE`](/schemas/SESSION_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 - a `payload.paymentInstrumentProperties.route` property is not a merchant partner enabled for the payment provider - `code` == `incompatible-state`: - the current verification session state does not permit session updates from the payment provider - HTTP 404 NOT FOUND with an error: - `code` == `not-found`: - `payload.verificationSessionId` does not identify a verification session that exists, or - `payload.verificationSessionId` does not identify a verification session the payment provider has access to type: object properties: id: $ref: '#/components/schemas/request-id' type: const: UPDATE_SESSION payload: type: object properties: verificationSessionId: $ref: '#/components/schemas/resource-id' description: > The verification session identifier generated by Bango. Bango provided this to the merchant partner to include in the message from the end user's device. paymentInstrumentProperties: $ref: '#/components/schemas/payment-instrument-properties-partial-patch' shared: description: > Update to the negotiation data shared from the payment provider to the merchant partner. Data in `paymentProviderToMerchant` is merged into the existing data. type: object properties: nextAction: $ref: '#/components/schemas/nextAction' paymentProviderToMerchant: $ref: '#/components/schemas/paymentProviderToMerchant' required: - verificationSessionId required: - id - type - payload GET_PI: title: GET_PI request action (inbound) description: > This action type lets a payment provider request the data stored for a payment instrument in the Bango Platform, specified using account identifiers. Merchant partners DO NOT see this data. ### Possible HTTP responses - HTTP 200 OK: - [`PI_RESPONSE`](/schemas/PI_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 - HTTP 404 NOT FOUND with an error: - `code` == `not-found`: - `payload.account` does not identify a payment instrument that exists, or - `payload.account` does not identify a payment instrument the payment provider has access to type: object properties: id: $ref: '#/components/schemas/request-id' type: const: GET_PI payload: type: object properties: account: $ref: '#/components/schemas/payment-instrument-account-properties' required: - account required: - id - type - payload UPDATE_PI: title: UPDATE_PI request action (inbound) description: > This action type lets a payment provider update some data stored for a payment instrument in the Bango Platform, specified using account identifiers. Merchant partners DO NOT see this data. The action permits changes to active payment instruments only, and to global and route properties only. It is not possible to update canceled payment instruments, or payment instrument account properties. ### Possible HTTP responses - HTTP 200 OK: - [`PI_RESPONSE`](/schemas/PI_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` specifies a canceled payment instrument, or - a `payload.paymentInstrumentProperties.route` property is not a merchant partner enabled for the payment provider - HTTP 404 NOT FOUND with an error: - `code` == `not-found`: - `payload.account` does not identify a payment instrument that exists, or - `payload.account` does not identify a payment instrument the payment provider has access to type: object properties: id: $ref: '#/components/schemas/request-id' type: const: UPDATE_PI payload: type: object properties: account: $ref: '#/components/schemas/payment-instrument-account-properties' description: | Account identifiers for the payment instrument to change. paymentInstrumentProperties: description: > A patch object for payment instrument properties, allowing a payment provider to patch (add, update, or remove): - Properties that apply universally across all merchants - Properties that apply for specific merchants type: object properties: global: $ref: >- #/components/schemas/payment-instrument-global-properties-patch route: $ref: '#/components/schemas/route' required: - account - paymentInstrumentProperties required: - id - type - payload NOTIFY_MO: title: NOTIFY_MO request action (inbound) description: > This action type lets a payment provider notify the Bango Platform of an MO message received by the payment provider. ### Possible HTTP responses - HTTP 204 NO CONTENT: - Simple acknowledgement - 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 - HTTP 404 NOT FOUND: - `code` == `not-found`: - `merchantId` is not recognized - merchant/payment provider route does not exist, or is not enabled, or does not support the MO flow - `sessionToken` is not recognized (when `sessionTokenType` is `bango` and there's no matching verification session ID) - HTTP 409 CONFLICT - `code` == `incompatible-state`: - the session `flow/state` was not `mo/awaiting-message` (`meta.reason` should explain that session is now in state `failed`) type: object properties: id: $ref: '#/components/schemas/request-id' type: const: NOTIFY_MO payload: type: object properties: account: $ref: '#/components/schemas/payment-instrument-account-properties' merchantId: $ref: '#/components/schemas/merchant-id' transport: $ref: '#/components/schemas/mo-transport' sessionToken: description: > Bango session token or merchant session token. Bango session tokens are always in UUID v4 format. Merchant session tokens may be any string. The session token DOES NOT include the `bango-session-rid:` prefix (for Bango session tokens) or any merchant-specific prefix like `DCB:`. type: string minLength: 1 maxLength: 256 example: b638c171-8e47-402d-a6d2-6cf29faf5711 sessionTokenType: description: > Whether sessionToken is a Bango session token or a merchant session token. In the MO message received by the payment provider, Bango session tokens have the prefix `bango-session-rid:` If this prefix is not present, a session token is treated as a merchant session token. type: string enum: - bango - merchant required: - account - merchantId - transport - sessionToken - sessionTokenType required: - id - type - payload SESSION_RESPONSE: title: SESSION_RESPONSE response action description: > The data stored for a verification session in the Bango Platform. Includes private data, data the payment provider has provided to the merchant, and data the merchant has provided to the payment provider. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: SESSION_RESPONSE payload: type: object properties: verificationSessionId: $ref: '#/components/schemas/resource-id' description: > The verification session identifier generated by Bango. Bango provided this to the merchant partner to include in the message from the end user's device. paymentProviderId: $ref: '#/components/schemas/payment-provider-id' merchantId: $ref: '#/components/schemas/merchant-id' paymentInstrumentProperties: $ref: '#/components/schemas/payment-instrument-properties-partial-patch' shared: description: > Current negotiation data shared between the payment provider and the merchant partner type: object properties: nextAction: $ref: '#/components/schemas/nextAction' paymentProviderToMerchant: $ref: '#/components/schemas/paymentProviderToMerchant' merchantToPaymentProvider: $ref: '#/components/schemas/merchantToPaymentProvider' required: - verificationSessionId - paymentProviderId - merchantId - paymentInstrumentProperties required: - id - type - payload PI_RESPONSE: title: PI_RESPONSE response action description: | The data stored for a payment instrument in the Bango Platform. type: object properties: id: $ref: '#/components/schemas/response-id' type: const: PI_RESPONSE payload: type: object properties: paymentInstrumentProperties: $ref: '#/components/schemas/payment-instrument-properties' required: - paymentInstrumentProperties required: - id - type - payload pi-already-canceled: title: pi-already-canceled [plan-p1] description: > The payment provider tried to cancel a payment instrument that is already canceled. type: object properties: code: const: pi-already-canceled meta: description: Empty in this case type: object message: description: Human-readable message describing the error const: Payment instrument already canceled url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/pi-already-canceled required: - code - meta - message incompatible-state: title: incompatible-state description: > Incompatible state. This is a generic error used when a more specific error is not available. The `meta.reason` may give a human-readable description of the error. type: object properties: code: const: incompatible-state meta: description: Additional information to help identify the specific error case type: object properties: reason: description: >- Human-readable information to explain in detail why the operation cannot be permitted in the current state. Code must not rely on the content of this string. type: string example: Operation is permitted in state "active" only message: description: Human-readable message describing the error const: The resource is not in the correct state for the requested operation url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/incompatible-state required: - code - meta - message namespace-id: title: Namespace ID description: > Globally unique namespace ID. These IDs are opaque, not guessable, and not sequential. Bango provides each Bango partner with a unique set of resource URIs. All resource URI paths start with `/ns/{nsid}`, where `{nsid}` is the namespace ID. No other Bango partner shares this namespace. Partner credentials permit access only to URIs with this namespace. type: string format: uuid example: 673c74de-ce5b-4f79-9851-2544d1d836cb 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 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 payment-instrument-properties-partial-patch: title: Payment instrument properties partial patch object description: > A **partial** patch object for payment instrument properties. A payment provider 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 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 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 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 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' example: accountType: prepaid locale: en-US currency: USD 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' 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 mo-transport: title: MO transport mechanism description: > How the MO message was delivered to the payment provider. Permitted values: - `sms`: MO message was delivered over SMS - `http-header-enrichment`: MO message was delivered over HTTP with user account details provided using Header Enrichment type: string enum: - sms - http-header-enrichment 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 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 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-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' 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' NotFound: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/not-found' TooManyRequests: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/too-many-requests' InternalServerError: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/internal-server-error' ServiceUnavailable: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/service-unavailable' 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 example: paymentEligibilityStatus: barred 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-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 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 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 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 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' example: accountType: prepaid locale: en-US currency: USD 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 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 not-found: title: not-found description: Not found or access denied type: object properties: code: const: not-found 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 requested resource was not found url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/not-found 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 internal-server-error: title: internal-server-error 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 request can be retried type: boolean default: true 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 service-unavailable: title: service-unavailable description: Service is unavailable type: object properties: code: const: service-unavailable 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 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 userProperties: title: User specific properties description: | Properties that are specific to a user type: object example: userProperties: token: myUserToken accountNickname: 457 specialProperty: key1: value1 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' NotFoundErrorResponse: description: > The requested resource was not found or access was denied. The API returns an identical error in both scenarios for data privacy reasons: API consumers can't find out anything about resources they aren't authorized to access. content: application/json: schema: $ref: '#/components/schemas/NotFound' 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' InternalServerErrorResponse: description: Unexpected internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' ServiceUnavailableErrorResponse: description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailable' securitySchemes: BasicAuth: type: http scheme: basic ````