> ## 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. # Perform a business operation related to an identity token > Use this endpoint to ask the Bango Platform to perform a business operation related to an identity token. A business operation might be an update to the token, or a task associated with the token. API consumers request business operations by sending _actions_ to this endpoint. An action specifies the business operation. The Bango Platform decides whether the business operation is permitted, and if so it performs the business operation. This might result in a change to the resource's properties, and might cause a side effect. 400 response error codes: - `invalid-json` if the request body isn't valid JSON format - `missing-parameter` if `type` is not present in the request body - `invalid-parameter` if `type` is not a valid action type - `missing-parameter` if `payload` is required and not present - `invalid-parameter` if `payload` is not the expected shape for the type of action (which may mean that `payload` is missing required parameters or some parameters are invalid: check the documentation to find out the expected payload shape for each action type) ## OpenAPI ````yaml /openapi/current/dcb-payments/merchant-to-bango/identity-token/openapi.yaml post /ns/{nsid}/identity/tokens/{rid}/actions openapi: 3.1.0 info: title: Bango Identity Token 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/tokens/{rid}/actions: post: tags: - env-production summary: Perform a business operation related to an identity token description: > Use this endpoint to ask the Bango Platform to perform a business operation related to an identity token. A business operation might be an update to the token, or a task associated with the token. API consumers request business operations by sending _actions_ to this endpoint. An action specifies the business operation. The Bango Platform decides whether the business operation is permitted, and if so it performs the business operation. This might result in a change to the resource's properties, and might cause a side effect. 400 response error codes: - `invalid-json` if the request body isn't valid JSON format - `missing-parameter` if `type` is not present in the request body - `invalid-parameter` if `type` is not a valid action type - `missing-parameter` if `payload` is required and not present - `invalid-parameter` if `payload` is not the expected shape for the type of action (which may mean that `payload` is missing required parameters or some parameters are invalid: check the documentation to find out the expected payload shape for each action type) operationId: identity-token-send-action parameters: - $ref: '#/components/parameters/NamespaceId' - $ref: '#/components/parameters/ResourceId' requestBody: description: > A request to perform a business operation related to an identity token. A request specifies an action `type` and any action-specific data (the `payload`). The response is always the latest version of the identity token held in the Bango Platform. The following action types are available. See each action type schema for detailed information. - [`CANCEL`](/schemas/CANCEL): A request to permanently disable a payment instrument token, with no possibility of undo - [`FETCH_ELIGIBILITY`](/schemas/FETCH_ELIGIBILITY): A request to fetch eligibility information for the token from the downstream payment provider - [`VALIDATE_PASSPHRASE`](/schemas/VALIDATE_PASSPHRASE): A request to validate passphrase for the token from the downstream payment provider - [`GET_ACCOUNT`](/schemas/GET_ACCOUNT): A request to retrieve the account information associated with a PIT required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/CANCEL' - $ref: '#/components/schemas/FETCH_ELIGIBILITY' - $ref: '#/components/schemas/VALIDATE_PASSPHRASE' - $ref: '#/components/schemas/GET_ACCOUNT' responses: '200': description: | The updated resource. content: application/vnd.bango.identity.token.v1+json: schema: $ref: '#/components/schemas/token-options' examples: CANCEL response: value: rid: 9dd4ac2d-83f3-4cba-a534-14c37f07da34 lastUpdate: '2023-03-14T15:54:00Z' type: payment-instrument-token state: active merchantId: AUSSIE_APPS paymentProviderId: OGNABTEL paymentEligibilityStatus: enabled accountType: postpaid locale: en-US customerProfile: spending_limit_profile userProperties: token: myUserToken accountNickname: 457 specialProperty: key1: value1 FETCH_ELIGIBILITY response: value: rid: 9dd4ac2d-83f3-4cba-a534-14c37f07da34 lastUpdate: '2023-03-14T15:54:00Z' type: payment-instrument-token state: active merchantId: AUSSIE_APPS paymentProviderId: OGNABTEL paymentEligibilityStatus: enabled accountType: postpaid locale: en-US customerProfile: spending_limit_profile userProperties: token: myUserToken accountNickname: 457 specialProperty: key1: value1 GET_ACCOUNT response: value: rid: 9dd4ac2d-83f3-4cba-a534-14c37f07da34 lastUpdate: '2023-03-14T15:54:00Z' type: payment-instrument-token state: active merchantId: AUSSIE_APPS paymentProviderId: OGNABTEL paymentEligibilityStatus: enabled accountType: postpaid locale: en-US customerProfile: spending_limit_profile account: phoneNumber: '+4402079304832' userProperties: token: myUserToken accountNickname: 457 specialProperty: key1: value1 VALIDATE_PASSPHRASE response: value: rid: 9dd4ac2d-83f3-4cba-a534-14c37f07da34 lastUpdate: '2023-03-14T15:54:00Z' type: payment-instrument-token state: active merchantId: AUSSIE_APPS paymentProviderId: OGNABTEL paymentEligibilityStatus: enabled accountType: postpaid locale: en-US customerProfile: spending_limit_profile passphraseValidationStatus: accepted userProperties: token: myUserToken accountNickname: 457 specialProperty: key1: value1 '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/InvalidCredentialsErrorResponse' '403': $ref: '#/components/responses/PermissionDeniedErrorResponse' '404': $ref: '#/components/responses/NotFoundErrorResponse' '409': description: | The token 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/pit-already-canceled' - $ref: '#/components/schemas/incompatible-state' required: - errors '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' '500': description: Unexpected internal server error or payment provider error content: application/json: schema: type: object properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/internal-server-error' - $ref: '#/components/schemas/payment-provider-failure' required: - errors '503': $ref: '#/components/responses/ServiceUnavailableErrorResponse' '504': $ref: '#/components/responses/GatewayTimeoutErrorResponse' components: parameters: NamespaceId: in: path name: nsid required: true schema: $ref: '#/components/schemas/namespace-id' ResourceId: in: path name: rid required: true schema: $ref: '#/components/schemas/resource-id' schemas: CANCEL: title: CANCEL action description: > A request to permanently disable a payment instrument token, with no possibility of undo. If the payment instrument token is already canceled, returns HTTP 409 with error code `pit-already-canceled`. type: object properties: type: const: CANCEL payload: description: Empty object type: object additionalProperties: false required: - type - payload FETCH_ELIGIBILITY: title: FETCH_ELIGIBILITY action description: > A request to fetch eligibility information for the token from the downstream payment provider. type: object properties: type: const: FETCH_ELIGIBILITY payload: description: | Data needed for the FETCH_ELIGIBILITY action. type: object properties: locale: $ref: '#/components/schemas/locale-bcp-47' description: > A [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag representing the locale of the merchant end user, if known. additionalProperties: false required: - type - payload VALIDATE_PASSPHRASE: title: VALIDATE_PASSPHRASE action description: > A request to validate passphrase secret for the token from the downstream payment provider. type: object properties: type: const: VALIDATE_PASSPHRASE payload: description: | Data needed for the VALIDATE_PASSPHRASE action. type: object properties: passphrase: type: string minLength: 1 maxLength: 50 description: > A plain text referring to a user passphrase that will be authenticated for the token from the downstream payment provider. required: - passphrase required: - type - payload GET_ACCOUNT: title: GET_ACCOUNT action description: | A request to retrieve the account information associated with a PIT type: object properties: type: const: GET_ACCOUNT payload: description: Empty object type: object additionalProperties: false required: - type - payload token-options: title: Identity Token resource description: | An identity Token resource response. oneOf: - $ref: '#/components/schemas/token-cancel' - $ref: '#/components/schemas/token-fetch-eligibility' - $ref: '#/components/schemas/token-validate-passphrase' - $ref: '#/components/schemas/token-get-account' pit-already-canceled: title: pit-already-canceled description: > An attempt was made to cancel a payment instrument token that is already canceled. type: object properties: code: const: pit-already-canceled meta: description: Empty in this case type: object message: description: Human-readable message describing the error const: Payment instrument token already canceled url: description: URL to more information about the error type type: string format: url example: https://developer.bango.com/error-codes/pit-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 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 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 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 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 token-cancel: title: Identity token resource - CANCEL selected description: | An identity token resource when CANCEL has been selected. allOf: - $ref: '#/components/schemas/BasicProperties' token-fetch-eligibility: title: Identity token resource - FETCH_ELIGIBILITY selected description: | An identity token resource FETCH_ELIGIBILITY has been selected. allOf: - $ref: '#/components/schemas/BasicProperties' token-validate-passphrase: title: Identity token resource- VALIDATE_PASSPHRASE selected description: | An identity token resource when VALIDATE_PASSPHRASE has been selected. allOf: - $ref: '#/components/schemas/BasicProperties' - $ref: '#/components/schemas/ExtendedPassphraseProperties' token-get-account: title: Identity token resource- GET_ACCOUNT selected description: | An identity token resource. when GET_ACCOUNT has been selected. allOf: - $ref: '#/components/schemas/BasicProperties' - $ref: '#/components/schemas/ExtendedAccountProperties' 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' ServiceUnavailable: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/service-unavailable' GatewayTimeout: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/gateway-timeout' BasicProperties: properties: rid: $ref: '#/components/schemas/resource-id' lastUpdate: type: string format: date-time description: | RFC 3339 datetime of the last update to this resource example: '2022-12-21T08:59:32Z' type: const: payment-instrument-token description: > The type of token. Code can use `type` to infer the schema for the rest of the resource. For now, only `payment-instrument-token` is supported. Other values may be supported in future. state: type: string enum: - active - canceled description: > The token state. Tokens of type `payment-instrument-token` are always one of: - `active`: may be used for payments, if eligible - `canceled`: may not be used for payments The only permitted state transition is from `active` to `canceled`. To make this transition, send a `CANCEL` action. It is not possible to transition from `canceled` back to `active`. merchantId: $ref: '#/components/schemas/merchant-id' paymentProviderId: $ref: '#/components/schemas/payment-provider-id' paymentEligibilityStatus: type: string enum: - discovering - enabled - not-enabled - closed - barred - unknown - unsupported description: > Information about the token related to payment processing. - `discovering`: The Bango Platform is currently waiting for a response from the payment provider about the token - `enabled`: Authorized partners can use the token to process payments - `not-enabled`: The payment provider has not enabled the token to process payments - `closed`: The payment provider has decided the token can no longer process payments (this is permanent) - `barred`: The payment provider has suspended or barred the user associated with the token (this may be temporary) - `unknown`: The payment provider has not provided information about this token - `unsupported`: The payment provider does not support requests for information about this token default: unknown accountType: $ref: '#/components/schemas/payment-provider-account-type' locale: $ref: '#/components/schemas/locale-bcp-47' description: > A [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag representing the locale of the merchant end user, if known. customerProfile: type: string description: | Customer’s latest spending limit profile userProperties: $ref: '#/components/schemas/userProperties' required: - rid - lastUpdate - type - state - merchantId - paymentProviderId ExtendedPassphraseProperties: properties: passphraseValidationStatus: $ref: '#/components/schemas/payment-provider-passphrase-validation-status' required: - passphraseValidationStatus ExtendedAccountProperties: properties: account: $ref: '#/components/schemas/payment-instrument-account-properties' required: - account 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 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 gateway-timeout: title: gateway-timeout description: Gateway timeout type: object properties: code: const: gateway-timeout 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 server timed out while waiting for a response from an upstream server, causing the request to fail required: - code - meta - message 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 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 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 userProperties: title: User specific properties description: | Properties that are specific to a user type: object example: userProperties: token: myUserToken accountNickname: 457 specialProperty: key1: value1 payment-provider-passphrase-validation-status: title: Payment provider passphrase validation status description: > The status returned by the payment provider resulting from passphrase validation. type: string enum: - accepted - declined - closed - barred - not-enabled - unknown 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 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' 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' ServiceUnavailableErrorResponse: description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailable' GatewayTimeoutErrorResponse: description: Gateway timeout. content: application/json: schema: $ref: '#/components/schemas/GatewayTimeout' securitySchemes: BasicAuth: type: http scheme: basic ````