> ## 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. # Retrieve an identity verification session > Use this endpoint to retrieve an identity verification session. The `flow` property of the session describes the selected identity verification flow, if any. The `state` property describes the current state of the session, and this may change over time. Partners can poll a session regularly to track asynchronous processes managed by the Bango Platform, such as sending messages to an end user's device through a payment provider's SMS service. To poll, partners can: - Use the `rid` of the session: this is a unique identifier (UUID v4) created by the Bango Platform - Use an alias for the `rid`, for example `partnerSessionId:fhie857jfskgiei`. (The Bango Platform creates this alias automatically if the partner specifies a `partnerSessionId` when creating the session) ## OpenAPI ````yaml /openapi/current/dcb-payments/merchant-to-bango/identity-verification/openapi.yaml get /ns/{nsid}/identity/verifications/{ridOrAlias} openapi: 3.1.0 info: title: Bango Identity Verification API version: 1.0.{build_number} contact: name: Bango Support url: https://developer.bango.com email: support@bango.com servers: - url: https://some-prod-tbd.bango.com description: Production server security: - BasicAuth: [] tags: - name: env-production description: Currently deployed to prod env - name: plan-later description: Not yet planned paths: /ns/{nsid}/identity/verifications/{ridOrAlias}: get: tags: - env-production summary: Retrieve an identity verification session description: > Use this endpoint to retrieve an identity verification session. The `flow` property of the session describes the selected identity verification flow, if any. The `state` property describes the current state of the session, and this may change over time. Partners can poll a session regularly to track asynchronous processes managed by the Bango Platform, such as sending messages to an end user's device through a payment provider's SMS service. To poll, partners can: - Use the `rid` of the session: this is a unique identifier (UUID v4) created by the Bango Platform - Use an alias for the `rid`, for example `partnerSessionId:fhie857jfskgiei`. (The Bango Platform creates this alias automatically if the partner specifies a `partnerSessionId` when creating the session) operationId: identity-verification-get parameters: - $ref: '#/components/parameters/NamespaceId' - $ref: '#/components/parameters/ResourceIdOrAlias' responses: '200': description: Resource found content: application/vnd.bango.identity.verification.v1+json: schema: $ref: '#/components/schemas/session' '401': $ref: '#/components/responses/InvalidCredentialsErrorResponse' '403': $ref: '#/components/responses/PermissionDeniedErrorResponse' '404': $ref: '#/components/responses/NotFoundErrorResponse' '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' ResourceIdOrAlias: in: path name: ridOrAlias required: true schema: oneOf: - $ref: '#/components/schemas/resource-id' - $ref: '#/components/schemas/alias-string' schemas: session: title: Identity Verification session description: | An identity verification session resource. oneOf: - $ref: '#/components/schemas/session-flow-none' - $ref: '#/components/schemas/session-flow-trusted' - $ref: '#/components/schemas/session-flow-negotiated' - $ref: '#/components/schemas/session-flow-mo' - $ref: '#/components/schemas/session-flow-mt' 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 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 alias-string: title: Alias string description: > A string that acts as an alternative identifier for another string. An alias always has two parts, in this order, separated by a colon: - A type - A unique ID corresponding to that type For example, `my-special-id:adrfhaerhu2`. A type may contain only alphanumeric characters and `-` characters, and must not be empty. IDs may be any non-empty string. The maximum length of an alias string, including type and ID, is 1000 bytes (encoded as UTF-8). For each partner namespace, the alias must be unique. For example, one namespace can contain aliases `abc:123` and `xyz:123`, but can't contain two aliases both called `abc:123` even if they correspond to different Bango-owned IDs. It's OK for two different namespaces each to contain an alias `abc:123`. type: string pattern: ^[-a-zA-Z0-9]+:.+$ maxLength: 1000 example: my-special-id:adrfhaerhu2 session-flow-none: title: Identity verification session - no flow selected description: | An identity verification session when no flow has been selected. type: object properties: rid: $ref: '#/components/schemas/resource-id' lastUpdate: $ref: '#/components/schemas/lastUpdate' partnerSessionId: $ref: '#/components/schemas/partnerSessionId' private: $ref: '#/components/schemas/private' shared: $ref: '#/components/schemas/identity-session-shared' flow: $ref: '#/components/schemas/flow-none' state: $ref: '#/components/schemas/state-flow-none' result: $ref: '#/components/schemas/result-flow-any' additionalProperties: false required: - rid - lastUpdate - flow - state session-flow-trusted: title: Identity verification session - Trusted flow selected description: > An identity verification session when the Trusted flow has been selected. type: object properties: rid: $ref: '#/components/schemas/resource-id' lastUpdate: $ref: '#/components/schemas/lastUpdate' partnerSessionId: $ref: '#/components/schemas/partnerSessionId' paymentProviderId: $ref: '#/components/schemas/payment-provider-id' private: $ref: '#/components/schemas/private' shared: $ref: '#/components/schemas/identity-session-shared' flow: $ref: '#/components/schemas/flow-trusted' state: $ref: '#/components/schemas/state-flow-trusted' result: $ref: '#/components/schemas/result-flow-any' paymentInstrumentToken: $ref: '#/components/schemas/paymentInstrumentToken-flow-trusted' additionalProperties: false required: - rid - lastUpdate - flow - state session-flow-negotiated: title: Identity verification session - Negotiated flow selected description: > An identity verification session when the Negotiated flow has been selected. type: object properties: rid: $ref: '#/components/schemas/resource-id' lastUpdate: $ref: '#/components/schemas/lastUpdate' partnerSessionId: $ref: '#/components/schemas/partnerSessionId' paymentProviderId: $ref: '#/components/schemas/payment-provider-id' private: $ref: '#/components/schemas/private' shared: $ref: '#/components/schemas/identity-session-shared' flow: $ref: '#/components/schemas/flow-negotiated' state: $ref: '#/components/schemas/state-flow-negotiated' result: $ref: '#/components/schemas/result-flow-any' paymentInstrumentToken: $ref: '#/components/schemas/paymentInstrumentToken-flow-negotiated' additionalProperties: false required: - rid - lastUpdate - flow - state session-flow-mo: title: Identity verification session - MO flow selected description: | An identity verification session when the MO flow has been selected. type: object properties: rid: $ref: '#/components/schemas/resource-id' lastUpdate: $ref: '#/components/schemas/lastUpdate' partnerSessionId: $ref: '#/components/schemas/partnerSessionId' paymentProviderId: $ref: '#/components/schemas/payment-provider-id' private: $ref: '#/components/schemas/private' shared: $ref: '#/components/schemas/identity-session-shared' flow: $ref: '#/components/schemas/flow-mo' state: $ref: '#/components/schemas/state-flow-mo' shortcode: $ref: '#/components/schemas/shortcode-flow-mo' messageBody: $ref: '#/components/schemas/messageBody-flow-mo' transport: $ref: '#/components/schemas/mo-transport' result: $ref: '#/components/schemas/result-flow-any' paymentInstrumentToken: $ref: '#/components/schemas/paymentInstrumentToken-flow-mo' partnerBillingToken: $ref: '#/components/schemas/partner-billing-token' additionalProperties: false required: - rid - lastUpdate - flow - state session-flow-mt: title: Identity verification session - MT flow selected description: | An identity verification session when the MT flow has been selected. type: object additionalProperties: false properties: rid: $ref: '#/components/schemas/resource-id' lastUpdate: $ref: '#/components/schemas/lastUpdate' partnerSessionId: $ref: '#/components/schemas/partnerSessionId' paymentProviderId: $ref: '#/components/schemas/payment-provider-id' private: $ref: '#/components/schemas/private' shared: $ref: '#/components/schemas/identity-session-shared' flow: $ref: '#/components/schemas/flow-mt' state: $ref: '#/components/schemas/state-flow-mt' otp: $ref: '#/components/schemas/otp-flow-mt' result: $ref: '#/components/schemas/result-flow-mt' paymentInstrumentToken: $ref: '#/components/schemas/paymentInstrumentToken-flow-mt' required: - rid - lastUpdate - flow - state 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' lastUpdate: type: string format: date-time description: | RFC 3339 datetime of the last update to this resource example: '2022-12-21T08:59:32Z' partnerSessionId: description: > A session ID supplied by the partner. This is assumed to be unique across all the partner's identity verification sessions. type: string minLength: 1 example: e9342a9f-ff3f-44ad-8e30-8a6f9a820060 private: description: > A place for the merchant partner to store private data related to the identity verification session. Once the payment instrument token is generated, this data is associated with the token. Merchant partners can initialize the data when creating a session, and can patch this data later when starting a flow or using an UPDATE_SESSION_DATA action. Supports any data (constraints TBD). This schema defines some commonly used properties. type: object properties: partnerCustomerId: description: > Optional. The partner's unique identifier for the end user. Bango treats this as an opaque string, which must not be empty. type: string minLength: 1 example: 6789812A OTHER: description: > Any other private data. TBD: constraints; other common properties, if any. identity-session-shared: title: Shared identity verification session properties description: > Data shared between the merchant partner and the payment provider as part of an identity verification session. type: object properties: 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 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 flow-none: const: none description: | No flow has been selected state-flow-none: description: > Describes the state of the resource when no flow has been selected. `state` is one of: - `authorizing` - the Bango Platform is checking for permission to create the session - `new` - the session is created and the Bango Platform is ready for the partner to select a flow - `failed` - the Bango Platform has denied the request to create the session - `closed` - the partner has decided to cancel the session without selecting a flow Typically partners see only `new`. `authorizing` is very short-lived, `failed` is possible but unlikely, and `closed` is only entered at the partner's request. type: string enum: - authorizing - new - failed - closed result-flow-any: title: Action result, if any description: > The result of the most recent action. There are three outcomes for an action: 1. The action was performed and completed with a positive outcome 2. The action was performed and completed with a negative outcome 3. The action was not performed because a required constraint was not met The result `code` indicates which outcome applied and is always a string in `lower-kebab-case`. The result `reasons` indicates any additional explanations available for the outcome (outcomes 2 and 3 above). For outcome 1 above, `reasons` is an empty array. type: object properties: code: description: > The outcome of the most recent action. This value gives you a high-level idea of _what happened_. type: string enum: - create-denied - create-failed - flow-denied - flow-failed - token-created example: token-created reasons: description: > Any explanations available to describe the outcome of the most recent action type: array items: oneOf: - $ref: '#/components/schemas/missing-parameter' - $ref: '#/components/schemas/invalid-parameter' - $ref: '#/components/schemas/incompatible-state' - $ref: '#/components/schemas/internal-server-error' - $ref: '#/components/schemas/service-unavailable' - $ref: '#/components/schemas/user-canceled' - $ref: '#/components/schemas/expired' - $ref: '#/components/schemas/payment-provider-failure' - $ref: '#/components/schemas/merchant-failure' - $ref: '#/components/schemas/user-invalid' - $ref: '#/components/schemas/user-barred' - $ref: '#/components/schemas/user-suspended' - $ref: '#/components/schemas/user-not-enabled' - $ref: '#/components/schemas/rejected' - $ref: '#/components/schemas/operation-not-supported' - $ref: '#/components/schemas/denied' - $ref: '#/components/schemas/unauthorized-flow' required: - code - reasons 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 flow-trusted: description: | Indicates the `trusted` identity verification flow was selected. const: trusted state-flow-trusted: description: > Describes the state of the resource when the Trusted flow has been selected. `state` is one of: - `authorizing` - the Bango Platform is checking for permission to start the flow - `creating-token` - the Bango Platform is obtaining the payment instrument token - `succeeded` - the Bango Platform has successfully obtained the payment instrument token (it's a property on the resource) - `failed` - the Bango Platform has denied the request to start the flow Typically partners only see `succeeded`. `authorizing` and `creating-token` are short-lived, and `failed` occurs when the partner is not authorized for this flow. type: string enum: - authorizing - creating-token - succeeded - failed paymentInstrumentToken-flow-trusted: description: > The payment instrument token obtained by the Bango Platform for the partner's end user. Only present in the resource when `state` is `succeeded`. type: string format: uuid flow-negotiated: description: | Indicates the `negotiated` identity verification flow was selected. const: negotiated state-flow-negotiated: description: > Describes the state of the resource when the Negotiated flow has been selected. `state` is one of: - `authorizing` - the Bango Platform is checking for permission to start the flow - `awaiting-confirmation` - the Bango Platform is awaiting confirmation of the end user's identity from the payment provider - `creating-token` - the payment provider confirmed the end user's identity and the Bango Platform is obtaining the payment instrument token - `succeeded` - the Bango Platform has successfully obtained the payment instrument token (it's a property on the resource) - `failed` - the Bango Platform has denied the request to start the flow, or the payment provider rejected the attempt to identify the end user Typically partners only see `awaiting-confirmation`, and `succeeded`. `authorizing` and `creating-token` are short-lived, and `failed` occurs when the partner is not authorized for this flow. type: string enum: - authorizing - awaiting-confirmation - creating-token - succeeded - failed paymentInstrumentToken-flow-negotiated: description: > The payment instrument token obtained by the Bango Platform for the partner's end user. Only present in the resource when `state` is `succeeded`. type: string format: uuid flow-mo: description: | Indicates the `mo` identity verification flow was selected. const: mo state-flow-mo: description: > Describes the state of the resource when the MO flow has been selected. `state` is one of: - `authorizing` - the Bango Platform is checking for permission to start the flow - `awaiting-message` - the Bango Platform is waiting for the MO message from the payment provider - `awaiting-confirmation` - the Bango Platform is awaiting confirmation of the end user's identity from the merchant - `creating-token` - the payment provider confirmed the end user's identity and the Bango Platform is obtaining the payment instrument token - `succeeded` - the Bango Platform has successfully obtained the payment instrument token (it's a property on the resource) - `failed` - the Bango Platform has denied the request to start the flow, or the merchant rejected the attempt to identify the end user, or there was a problem with the MO message Typically partners only see `awaiting-message`, `awaiting-confirmation`, and `succeeded`. `authorizing` and `creating-token` are short-lived, and `failed` occurs in case of errors. type: string enum: - authorizing - awaiting-message - awaiting-confirmation - creating-token - succeeded - failed shortcode-flow-mo: description: > Shortcode the merchant must use to send the message to the payment provider. Sourced from billing-route-service. Omitted if we don't need to tell the merchant, or if the merchant did not create the verification session itself. type: string pattern: ^[0-9]{1,20}$ example: '12345' messageBody-flow-mo: description: > The full text of the message the merchant must send from the end user's device to the payment provider (using the shortcode if supplied). Static string `bango-session-rid:` followed by the verification session rid. Always exactly 54 bytes. Omitted if the merchant did not create the verification session itself. Present if it did. type: string minLength: 54 maxLength: 54 example: bango-session-rid:68aec572-c34e-4f68-aa80-10300c4dc06b 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 paymentInstrumentToken-flow-mo: description: > The payment instrument token obtained by the Bango Platform for the partner's end user. Only present in the resource when `state` is `succeeded`. type: string format: uuid partner-billing-token: title: Partner billing token description: > A partner billing token to be used later by the partner in payment transactions. It may be present only after being provided by the partner in a previous confirm session identity request. type: string minLength: 1 maxLength: 100 flow-mt: description: | Indicates the `mt` identity verification flow was selected. const: mt state-flow-mt: description: > Describes the state of the resource when the MT flow has been selected. `state` is one of: - `authorizing` - the Bango Platform is checking for permission to start the flow - `processing-otp` - the Bango Platform is creating, validating, renewing, or resetting an OTP - `processing-pp-otp` - the Bango Platform has asked the payment provider to send or verify an OTP - `sending-otp` - the Bango Platform has asked the payment provider to send the OTP to the user, and is waiting for a response - `awaiting-user-otp` - the Bango Platform is waiting for the merchant to send an action related to the OTP: verify, reset, or resent - `creating-token` - the merchant end user entered the OTP correctly and the Bango Platform is obtaining the payment instrument token - `succeeded` - the Bango Platform has successfully obtained the payment instrument token (it's a property on the resource) - `failed` - the Bango Platform has denied the request to start the flow, or the payment provider fatally denied the request to send the MT message to the end user, or a service error occurred Typically partners only see `awaiting-user-otp` and `succeeded`. `authorizing`, `processing-otp`, `processing-pp-otp`, `sending-otp`, and `creating-token` are short-lived, and `failed` occurs in case of errors. type: string enum: - authorizing - processing-otp - processing-pp-otp - sending-otp - awaiting-user-otp - creating-token - succeeded - failed otp-flow-mt: title: OTP properties description: > Properties useful to the merchant about the current OTP and retries and resets available. Only used for Bango-managed OTPs. type: object additionalProperties: false properties: triesUntilReset: description: > How many attempts remain for the merchant end user to type the current OTP before a reset occurs, if available type: integer minimum: 0 example: 3 resetsAvailable: description: > How many times the merchant may request to generate a new OTP within the session. When `triesUntilReset` and `resetsAvailable` are both zero, the session ends in failure. type: integer minimum: 0 example: 5 validUntil: description: > RFC 3339 datetime after which the current OTP expires. On expiry, any attempt to verify the OTP fails and a reset occurs, if available type: string format: date-time example: '2024-02-06T18:31:36Z' result-flow-mt: title: Action result, if any description: > The result of the most recent action. The result `code` indicates what happened and is always a string in `lower-kebab-case`. The result `reasons` indicates any additional explanations available. It might be an empty array. type: object properties: code: description: > The outcome of the most recent action. This value gives you a high-level idea of _what happened_. Route configuration identifies which actor manages OTPs for the flow: either the Bango Platform or the payment provider. - Values marked with [B] are returned only when the Bango Platform manages the OTPs - Values marked with [PP] are returned only when the payment provider manages the OTPs - Values without a marker are returned in either case Possible values: - `create-denied` - Bango Platform denied the request to create the session - `create-failed` - Bango Platform encountered an error while creating the session - `flow-denied` - Bango Platform or payment provider denied the request to start a flow. Occurs if the payment provider doesn't recognize the account properties supplied - `flow-failed` - Bango Platform encountered an error while performing an internal operation - `token-created` - Bango Platform successfully created the payment instrument token - `otp-created-send-requested` [B] - Merchant started flow - Bango Platform generated the first OTP and asked the payment provider to send it to the end user - `otp-reset-send-requested` [B] - Merchant requested RESET, or RESEND of an expired OTP - Bango Platform reset the OTP, and asked the payment provider to send it to the end user - `otp-resend-requested` [B] - Merchant requested RESEND of an unexpired OTP - Bango Platform reset the expiry date and asked the payment provider to send the current OTP to the end user again - `otp-expired-send-requested` [B] - Merchant requested VERIFY of an expired OTP - Bango Platform generated a new OTP and asked the payment provider to send it to the end user - `otp-incorrect-send-requested` [B] - Merchant requested VERIFY of an unexpired OTP, the supplied OTP was incorrect, no more attempts remain for that OTP, but resets are available - Bango Platform generated a new OTP and asked the payment provider to send it to the end user - `otp-send-requested` [PP] - Bango Platform asked the payment provider to generate and send an OTP to the end user, or send an unexpired OTP it generated earlier - `otp-send-request-denied` [PP] - Bango Platform asked the payment provider to generate and send an OTP to the end user, or send an unexpired OTP it generated earlier, but payment provider denied the request for security reasons - `otp-send-request-failure` [B] - Any merchant action - Bango Platform asked the payment provider to send an OTP to the end user, and the payment provider did not accept the request - Merchant should RESEND - `otp-expired-must-resend` [B] - Merchant requested VERIFY of an expired OTP - Bango Platform generated a new OTP - Bango Platform is configured to wait for the merchant to request RESEND - `otp-expired` [PP] - Merchant requested VERIFY, and the payment provider reported that the OTP has expired. Merchant should request RESET - `otp-incorrect-must-resend` [B] - Merchant requested VERIFY of an unexpired OTP, the supplied OTP was incorrect, no more attempts remain for that OTP, but resets are available - Bango Platform generated a new OTP - Bango Platform is configured to wait for the merchant to request RESEND - `otp-incorrect` - Merchant requested VERIFY of an unexpired OTP, and the supplied OTP was incorrect. For a Bango-managed OTP, more attempts remain for that OTP. For a payment-provider-managed OTP, more attempts MIGHT remain - Merchant can request VERIFY again, or RESET, or RESEND - `otp-reset-not-available` [B] - Merchant requested RESET and more attempts are available but no resets, OR - Merchant requested RESEND of an expired OTP and no resets are available - `otp-incorrect-final-attempt` - Merchant requested VERIFY, the supplied OTP was incorrect, and now there are no more retries or resets available - Bango Platform closed the session in state `failed` - `session-ended` [B] - Merchant requested VERIFY when no retries or resets are available, OR - Merchant requested RESET when no retries or resets are available, OR - Merchant requested RESEND of an expired OTP and no retries or resets are available - `flow-temporary-error` [B] - Bango Platform encountered a temporary internal error - Merchant should try again - `pp-otp-error` [PP] - Bango Platform asked the payment provider to send an OTP to a merchant end user, or verify an OTP supplied by a merchant end user, and an error occurred at the payment provider - Merchant should try again - `unknown` - An unknown error occurred - Merchant should try again type: string enum: - create-denied - create-failed - flow-denied - flow-failed - token-created - otp-created-send-requested - otp-reset-send-requested - otp-resend-requested - otp-expired-send-requested - otp-incorrect-send-requested - otp-send-requested - otp-send-request-denied - otp-send-request-failure - otp-expired-must-resend - otp-expired - otp-incorrect-must-resend - otp-incorrect - otp-reset-not-available - otp-incorrect-final-attempt - session-ended - flow-temporary-error - pp-otp-error - unknown example: token-created reasons: description: > Any explanations available to describe the outcome of the most recent action. Empty if no more details are available or needed. type: array items: oneOf: - $ref: '#/components/schemas/missing-parameter' - $ref: '#/components/schemas/invalid-parameter' - $ref: '#/components/schemas/incompatible-state' - $ref: '#/components/schemas/internal-server-error' - $ref: '#/components/schemas/service-unavailable' - $ref: '#/components/schemas/user-canceled' - $ref: '#/components/schemas/expired' - $ref: '#/components/schemas/payment-provider-failure' - $ref: '#/components/schemas/merchant-failure' - $ref: '#/components/schemas/user-invalid' - $ref: '#/components/schemas/user-barred' - $ref: '#/components/schemas/user-suspended' - $ref: '#/components/schemas/user-not-enabled' - $ref: '#/components/schemas/rejected' - $ref: '#/components/schemas/operation-not-supported' - $ref: '#/components/schemas/denied' - $ref: '#/components/schemas/unauthorized-flow' required: - code - reasons paymentInstrumentToken-flow-mt: description: > The payment instrument token obtained by the Bango Platform for the partner's end user. Only present in the resource when `state` is `succeeded`. type: string format: uuid CommonErrorResponse: type: object required: - errors 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 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 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 user-canceled: title: user-canceled description: > The payment provider denied a requested action because the user canceled. type: object properties: code: const: user-canceled meta: description: Empty in this case type: object message: description: Human-readable message describing the error type: string url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/user-canceled required: - code - meta - message expired: title: expired description: > The payment provider denied a requested action because the authority to perform the action has expired. For example, if too much time has passed since a payment was authorized, the payment provider might return an `expired` error. type: object properties: code: const: expired meta: description: Empty in this case type: object message: description: Human-readable message describing the error type: string url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/expired required: - code - meta - message payment-provider-failure: title: payment-provider-failure description: > An error occurred with the downstream payment provider, and the Bango Platform was unable to fulfil the request. This might be a transient error or a persistent error. The `meta.paymentProviderCode` value indicates the type of response received by the Bango Platform from the payment provider. The `meta.canRetry` boolean indicates whether the payment provider believes the merchant can retry the request. type: object properties: code: const: payment-provider-failure meta: description: Additional information to help identify the specific error case type: object properties: paymentProviderCode: description: > Code indicating the type of response the Bango Platform received from the payment provider. Not all codes apply to all requests from the Bango Platform. Possible values: - `service-unavailable`: the payment provider returned an HTTP 503 response to a request from the Bango Platform - `internal-server-error`: the payment provider returned another HTTP 5xx response to a request from the Bango Platform - `mt-message-send-request-failure`: the payment provider was unable to send an MT flow message to an end user's device - `otp-request-failure`: the payment provider was unable to send an OTP to an end user's device, or verify an OTP provided by an end user type: string enum: - internal-server-error - service-unavailable - mt-message-send-request-failure - otp-request-failure canRetry: description: Whether the payment provider believes the request can be retried type: boolean required: - paymentProviderCode - canRetry message: description: Human-readable message describing the error const: An error occurred at the payment provider url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/payment-provider-failure required: - code - meta - message merchant-failure: title: merchant-failure description: > An error occurred with the upstream merchant, and the Bango Platform was unable to fulfil the request. This might be a transient error or a persistent error. The `meta.merchantCode` value indicates the type of response received by the Bango Platform from the merchant. type: object properties: code: const: merchant-failure meta: description: Additional information to help identify the specific error case type: object properties: merchantCode: description: > Code indicating the type of response received by the Bango Platform from the merchant. type: string enum: - internal-server-error - service-unavailable required: - merchantCode message: description: Human-readable message describing the error const: An error occurred at the merchant url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/merchant-failure required: - code - meta - message user-invalid: title: user-invalid description: > The payment provider denied a requested action because the user does not exist or is invalid in some way. type: object properties: code: const: user-invalid meta: description: Empty in this case type: object message: description: Human-readable message describing the error type: string url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/user-invalid required: - code - meta - message user-barred: title: user-barred description: | The requested action was denied because the user has been barred. type: object properties: code: const: user-barred meta: description: Empty in this case type: object message: description: Human-readable message describing the error type: string url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/user-barred required: - code - meta - message user-suspended: title: user-suspended description: > The payment provider denied a requested action because the user has been suspended. type: object properties: code: const: user-suspended meta: description: Empty in this case type: object message: description: Human-readable message describing the error type: string url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/user-suspended required: - code - meta - message user-not-enabled: title: user-not-enabled description: > The requested action was denied because the user is not currently enabled. type: object properties: code: const: user-not-enabled meta: description: Empty in this case type: object message: description: Human-readable message describing the error type: string url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/user-not-enabled required: - code - meta - message rejected: title: rejected description: > The responsible partner decided not to confirm the identity of an end user as part of an identity verification flow, and did not supply a specific error code. The `message` may contain more information. The identity verification flow for the session determines whether the responsible partner is the payment provider or the merchant. type: object properties: code: const: rejected meta: description: Empty in this case type: object message: description: Human-readable message describing the error type: string url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/rejected required: - code - meta - message operation-not-supported: title: operation-not-supported description: > The payment provider denied a requested action because it does not support the operation. type: object properties: code: const: operation-not-supported meta: description: Empty in this case type: object message: description: Human-readable message describing the error type: string url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/operation-not-supported required: - code - meta - message denied: title: denied description: > The payment provider denied a requested action without supplying a specific error code. The `message` may contain more information. type: object properties: code: const: denied meta: description: Empty in this case type: object message: description: Human-readable message describing the error type: string url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/denied required: - code - meta - message unauthorized-flow: title: unauthorized-flow description: | The merchant is not authorized to use the requested flow. type: object properties: code: const: unauthorized-flow meta: description: Empty in this case type: object message: description: Human-readable message describing the error const: Not authorized to start requested flow url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/unauthorized-flow required: - code - meta - message responses: 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 ````