From 61be3a209ec45d69ea80fb5dbadce5e35adaad50 Mon Sep 17 00:00:00 2001 From: Aaryaman Bhute Date: Mon, 13 Jul 2026 22:25:13 +0000 Subject: [PATCH] feat: sandbox simulate endpoints for the full card-event set Add 7 sandbox card-event simulate endpoints, mirroring the existing authorization/clearing/return simulators: balance_inquiry, credit_authorization, financial_authorization, financial_credit_authorization, authorization_advice, credit_authorization_advice, return_reversal. All POST, sandbox-only, 202 -> { issuerTransactionToken }. Correct the existing 3 simulators' documented success response from 200/CardTransaction to 202/SandboxCardSimulationResponse to match the actual issuer-driven, webhook-delivered behavior. Authorization expiry and authorization reversal/void are intentionally excluded (no card-issuer simulate path). Co-Authored-By: aaryamanbhute --- .redocly.lint-ignore.yaml | 8 + .spectral.yaml | 7 +- mintlify/openapi.yaml | 577 +++++++++++++++++- openapi.yaml | 577 +++++++++++++++++- ...SandboxCardAuthorizationAdviceRequest.yaml | 22 + .../SandboxCardBalanceInquiryRequest.yaml | 10 + .../cards/SandboxCardSimulationResponse.yaml | 15 + .../SandboxCardTransactionRefRequest.yaml | 12 + openapi/openapi.yaml | 14 + ...box_cards_{id}_simulate_authorization.yaml | 9 +- ...ds_{id}_simulate_authorization_advice.yaml | 77 +++ ...x_cards_{id}_simulate_balance_inquiry.yaml | 78 +++ .../sandbox_cards_{id}_simulate_clearing.yaml | 9 +- ...ds_{id}_simulate_credit_authorization.yaml | 86 +++ ..._simulate_credit_authorization_advice.yaml | 87 +++ ...{id}_simulate_financial_authorization.yaml | 87 +++ ...mulate_financial_credit_authorization.yaml | 86 +++ .../sandbox_cards_{id}_simulate_return.yaml | 9 +- ...x_cards_{id}_simulate_return_reversal.yaml | 79 +++ 19 files changed, 1820 insertions(+), 29 deletions(-) create mode 100644 openapi/components/schemas/cards/SandboxCardAuthorizationAdviceRequest.yaml create mode 100644 openapi/components/schemas/cards/SandboxCardBalanceInquiryRequest.yaml create mode 100644 openapi/components/schemas/cards/SandboxCardSimulationResponse.yaml create mode 100644 openapi/components/schemas/cards/SandboxCardTransactionRefRequest.yaml create mode 100644 openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_advice.yaml create mode 100644 openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_balance_inquiry.yaml create mode 100644 openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_credit_authorization.yaml create mode 100644 openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_credit_authorization_advice.yaml create mode 100644 openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_financial_authorization.yaml create mode 100644 openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_financial_credit_authorization.yaml create mode 100644 openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml diff --git a/.redocly.lint-ignore.yaml b/.redocly.lint-ignore.yaml index 9652a98a5..8b949d3fc 100644 --- a/.redocly.lint-ignore.yaml +++ b/.redocly.lint-ignore.yaml @@ -14,3 +14,11 @@ openapi.yaml: - '#/paths/~1quotes/post/requestBody/content/application~1json/schema' no-ambiguous-paths: - '#/paths/~1customers~1external-accounts~1{externalAccountId}' + paths-kebab-case: + - '#/paths/~1sandbox~1cards~1{id}~1simulate~1balance_inquiry' + - '#/paths/~1sandbox~1cards~1{id}~1simulate~1credit_authorization' + - '#/paths/~1sandbox~1cards~1{id}~1simulate~1financial_authorization' + - '#/paths/~1sandbox~1cards~1{id}~1simulate~1financial_credit_authorization' + - '#/paths/~1sandbox~1cards~1{id}~1simulate~1authorization_advice' + - '#/paths/~1sandbox~1cards~1{id}~1simulate~1credit_authorization_advice' + - '#/paths/~1sandbox~1cards~1{id}~1simulate~1return_reversal' diff --git a/.spectral.yaml b/.spectral.yaml index ad9f01377..6975a563e 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -165,7 +165,10 @@ rules: # Paths (README: Resources) # ============================================================ - # Paths should use kebab-case (path params in {camelCase} are allowed) + # Paths should use kebab-case (path params in {camelCase} are allowed). + # The /sandbox/cards/{id}/simulate/* endpoints are exempted (second branch of + # the pattern): their snake_case segments mirror the card issuer's simulate + # routes verbatim, and the SDK must call those exact deployed URLs. paths-kebab-case: description: Path segments should use kebab-case message: "Path should use kebab-case (e.g., /external-accounts not /externalAccounts). See openapi/README.md#resources" @@ -175,4 +178,4 @@ rules: field: "@key" function: pattern functionOptions: - match: "^(\\/([a-z0-9]+(-[a-z0-9]+)*|\\{[a-zA-Z0-9]+\\}))+$" + match: "^((\\/([a-z0-9]+(-[a-z0-9]+)*|\\{[a-zA-Z0-9]+\\}))+|\\/sandbox\\/cards\\/\\{id\\}\\/simulate\\/(balance_inquiry|credit_authorization|financial_authorization|financial_credit_authorization|authorization_advice|credit_authorization_advice|return_reversal))$" diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index e4bea8865..1765a83d8 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -7298,12 +7298,12 @@ paths: mcc: '5942' country: US responses: - '200': - description: Simulated authorization processed. Returns the resulting card transaction. + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. content: application/json: schema: - $ref: '#/components/schemas/CardTransaction' + $ref: '#/components/schemas/SandboxCardSimulationResponse' '400': description: Bad request - Invalid parameters content: @@ -7376,12 +7376,12 @@ paths: cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 amount: 0 responses: - '200': - description: Simulated clearing processed. Returns the updated card transaction. + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. content: application/json: schema: - $ref: '#/components/schemas/CardTransaction' + $ref: '#/components/schemas/SandboxCardSimulationResponse' '400': description: Bad request - Invalid parameters content: @@ -7445,12 +7445,526 @@ paths: cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 amount: 1500 responses: - '200': - description: Simulated return processed. Returns the updated card transaction. + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card or card transaction not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/balance_inquiry: + post: + summary: Simulate a card balance inquiry + description: | + Simulate a balance-inquiry authorization against a card in the sandbox environment. A balance inquiry is always a `0`-amount authorization, so the request carries no `amount` — only the `merchant`. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + Production returns `404` on this path. + operationId: sandboxSimulateCardBalanceInquiry + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a balance inquiry against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardBalanceInquiryRequest' + examples: + balanceInquiry: + summary: Balance inquiry at a fuel pump + value: + merchant: + descriptor: SHELL OIL 12345678 + mcc: '5541' + country: US + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/credit_authorization: + post: + summary: Simulate a card credit authorization + description: | + Simulate an inbound credit authorization (a merchant-initiated credit to the card, e.g. a refund pushed as an authorization) in the sandbox environment. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + As with `simulate/authorization`, the decisioning outcome is controlled by the last three characters of `merchant.descriptor` — see the `simulate/authorization` suffix table. + + Production returns `404` on this path. + operationId: sandboxSimulateCardCreditAuthorization + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a credit authorization against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardAuthorizationRequest' + examples: + creditAuth: + summary: $25.00 credit authorization + value: + amount: 2500 + currency: + code: USD + merchant: + descriptor: ACME MARKETPLACE + mcc: '5942' + country: US + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/financial_authorization: + post: + summary: Simulate a card financial authorization + description: | + Simulate a single-message financial authorization (an authorization that clears in the same message, e.g. an ATM withdrawal or other dual-message-exempt flow) against a card in the sandbox environment. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + As with `simulate/authorization`, the decisioning outcome is controlled by the last three characters of `merchant.descriptor` — see the `simulate/authorization` suffix table. + + Production returns `404` on this path. + operationId: sandboxSimulateCardFinancialAuthorization + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a financial authorization against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardAuthorizationRequest' + examples: + financialAuth: + summary: $80.00 single-message ATM withdrawal + value: + amount: 8000 + currency: + code: USD + merchant: + descriptor: ATM WITHDRAWAL 24TH ST + mcc: '6011' + country: US + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/financial_credit_authorization: + post: + summary: Simulate a card financial credit authorization + description: | + Simulate a single-message financial credit authorization (a credit to the card that clears in the same message, e.g. an ATM deposit or push credit) against a card in the sandbox environment. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + As with `simulate/authorization`, the decisioning outcome is controlled by the last three characters of `merchant.descriptor` — see the `simulate/authorization` suffix table. + + Production returns `404` on this path. + operationId: sandboxSimulateCardFinancialCreditAuthorization + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a financial credit authorization against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardAuthorizationRequest' + examples: + financialCreditAuth: + summary: $40.00 single-message push credit + value: + amount: 4000 + currency: + code: USD + merchant: + descriptor: ACME PAYOUTS + mcc: '6012' + country: US + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. content: application/json: schema: - $ref: '#/components/schemas/CardTransaction' + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/authorization_advice: + post: + summary: Simulate a card authorization advice + description: | + Simulate an `AUTHORIZATION_ADVICE` that re-sizes an existing open authorization on a `CardTransaction` in the sandbox environment. The `amount` is the new *total* authorized amount the advice re-sizes to. The parent transaction must be in `AUTHORIZED` or `PARTIALLY_SETTLED` state. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + Production returns `404` on this path. + operationId: sandboxSimulateCardAuthorizationAdvice + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the advice applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardAuthorizationAdviceRequest' + examples: + resizeUp: + summary: Re-size an open auth up to a new total of $20.00 + value: + cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 + amount: 2000 + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card or card transaction not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/credit_authorization_advice: + post: + summary: Simulate a card credit authorization advice + description: | + Simulate a network-initiated `CREDIT_AUTHORIZATION_ADVICE` against a card in the sandbox environment. Like `simulate/credit_authorization`, it is keyed by the card (PAN) and `merchant` rather than an existing transaction. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + As with `simulate/authorization`, the decisioning outcome is controlled by the last three characters of `merchant.descriptor` — see the `simulate/authorization` suffix table. + + Production returns `404` on this path. + operationId: sandboxSimulateCardCreditAuthorizationAdvice + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the advice applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardAuthorizationRequest' + examples: + creditAdvice: + summary: $25.00 credit authorization advice + value: + amount: 2500 + currency: + code: USD + merchant: + descriptor: ACME MARKETPLACE + mcc: '5942' + country: US + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/return_reversal: + post: + summary: Simulate a card return reversal + description: | + Simulate a `RETURN_REVERSAL` against an existing `REFUNDED` card transaction in the sandbox environment — reversing a previously settled return. The parent transaction must be in `REFUNDED` state. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + Note: authorization reversal / void has no dedicated card-issuer simulate path (the void simulator emits a distinct `VOID` event), so — like authorization expiry — it is not exposed here. + + Production returns `404` on this path. + operationId: sandboxSimulateCardReturnReversal + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the return reversal applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardTransactionRefRequest' + examples: + returnReversal: + summary: Reverse a settled return on a refunded transaction + value: + cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' '400': description: Bad request - Invalid parameters content: @@ -20176,6 +20690,16 @@ components: $ref: '#/components/schemas/Currency' merchant: $ref: '#/components/schemas/CardMerchant' + SandboxCardSimulationResponse: + type: object + required: + - issuerTransactionToken + description: Response body for the sandbox card-event simulators. The simulate call pokes the card issuer's sandbox; the resulting card operation is delivered asynchronously via the issuer's events webhook, never synchronously in this response. + properties: + issuerTransactionToken: + type: string + description: The card issuer's transaction token for the simulated event. Correlates the eventual webhook-delivered card operation back to this simulate call. + example: f3a1c2d4-5b6e-7890-abcd-ef0123456789 SandboxCardClearingRequest: type: object required: @@ -20210,6 +20734,41 @@ components: description: Return amount in the smallest unit of the transaction's currency. Must be less than or equal to the net settled amount (settled minus previously-refunded). exclusiveMinimum: 0 example: 1500 + SandboxCardBalanceInquiryRequest: + type: object + required: + - merchant + description: Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/balance_inquiry`. Drives a balance-inquiry authorization against the card. A balance inquiry is always a `0`-amount authorization, so it carries no `amount`. + properties: + merchant: + $ref: '#/components/schemas/CardMerchant' + SandboxCardAuthorizationAdviceRequest: + type: object + required: + - cardTransactionId + - amount + description: Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/authorization_advice`. Drives an `AUTHORIZATION_ADVICE` that re-sizes an existing open authorization. + properties: + cardTransactionId: + type: string + description: The id of the `CardTransaction` the advice re-sizes. Must be in `AUTHORIZED` or `PARTIALLY_SETTLED` state. + example: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 + amount: + type: integer + format: int64 + description: The new *total* authorized amount, in the smallest unit of the transaction's currency, that the advice re-sizes the authorization to. + exclusiveMinimum: 0 + example: 2000 + SandboxCardTransactionRefRequest: + type: object + required: + - cardTransactionId + description: Sandbox-only request body for simulate endpoints keyed only by an existing card transaction — currently `POST /sandbox/cards/{id}/simulate/return_reversal`. + properties: + cardTransactionId: + type: string + description: The id of the `CardTransaction` to act against. + example: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 StablecoinProvider: type: string enum: diff --git a/openapi.yaml b/openapi.yaml index e4bea8865..1765a83d8 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7298,12 +7298,12 @@ paths: mcc: '5942' country: US responses: - '200': - description: Simulated authorization processed. Returns the resulting card transaction. + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. content: application/json: schema: - $ref: '#/components/schemas/CardTransaction' + $ref: '#/components/schemas/SandboxCardSimulationResponse' '400': description: Bad request - Invalid parameters content: @@ -7376,12 +7376,12 @@ paths: cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 amount: 0 responses: - '200': - description: Simulated clearing processed. Returns the updated card transaction. + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. content: application/json: schema: - $ref: '#/components/schemas/CardTransaction' + $ref: '#/components/schemas/SandboxCardSimulationResponse' '400': description: Bad request - Invalid parameters content: @@ -7445,12 +7445,526 @@ paths: cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 amount: 1500 responses: - '200': - description: Simulated return processed. Returns the updated card transaction. + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card or card transaction not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/balance_inquiry: + post: + summary: Simulate a card balance inquiry + description: | + Simulate a balance-inquiry authorization against a card in the sandbox environment. A balance inquiry is always a `0`-amount authorization, so the request carries no `amount` — only the `merchant`. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + Production returns `404` on this path. + operationId: sandboxSimulateCardBalanceInquiry + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a balance inquiry against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardBalanceInquiryRequest' + examples: + balanceInquiry: + summary: Balance inquiry at a fuel pump + value: + merchant: + descriptor: SHELL OIL 12345678 + mcc: '5541' + country: US + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/credit_authorization: + post: + summary: Simulate a card credit authorization + description: | + Simulate an inbound credit authorization (a merchant-initiated credit to the card, e.g. a refund pushed as an authorization) in the sandbox environment. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + As with `simulate/authorization`, the decisioning outcome is controlled by the last three characters of `merchant.descriptor` — see the `simulate/authorization` suffix table. + + Production returns `404` on this path. + operationId: sandboxSimulateCardCreditAuthorization + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a credit authorization against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardAuthorizationRequest' + examples: + creditAuth: + summary: $25.00 credit authorization + value: + amount: 2500 + currency: + code: USD + merchant: + descriptor: ACME MARKETPLACE + mcc: '5942' + country: US + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/financial_authorization: + post: + summary: Simulate a card financial authorization + description: | + Simulate a single-message financial authorization (an authorization that clears in the same message, e.g. an ATM withdrawal or other dual-message-exempt flow) against a card in the sandbox environment. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + As with `simulate/authorization`, the decisioning outcome is controlled by the last three characters of `merchant.descriptor` — see the `simulate/authorization` suffix table. + + Production returns `404` on this path. + operationId: sandboxSimulateCardFinancialAuthorization + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a financial authorization against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardAuthorizationRequest' + examples: + financialAuth: + summary: $80.00 single-message ATM withdrawal + value: + amount: 8000 + currency: + code: USD + merchant: + descriptor: ATM WITHDRAWAL 24TH ST + mcc: '6011' + country: US + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/financial_credit_authorization: + post: + summary: Simulate a card financial credit authorization + description: | + Simulate a single-message financial credit authorization (a credit to the card that clears in the same message, e.g. an ATM deposit or push credit) against a card in the sandbox environment. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + As with `simulate/authorization`, the decisioning outcome is controlled by the last three characters of `merchant.descriptor` — see the `simulate/authorization` suffix table. + + Production returns `404` on this path. + operationId: sandboxSimulateCardFinancialCreditAuthorization + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a financial credit authorization against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardAuthorizationRequest' + examples: + financialCreditAuth: + summary: $40.00 single-message push credit + value: + amount: 4000 + currency: + code: USD + merchant: + descriptor: ACME PAYOUTS + mcc: '6012' + country: US + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. content: application/json: schema: - $ref: '#/components/schemas/CardTransaction' + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/authorization_advice: + post: + summary: Simulate a card authorization advice + description: | + Simulate an `AUTHORIZATION_ADVICE` that re-sizes an existing open authorization on a `CardTransaction` in the sandbox environment. The `amount` is the new *total* authorized amount the advice re-sizes to. The parent transaction must be in `AUTHORIZED` or `PARTIALLY_SETTLED` state. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + Production returns `404` on this path. + operationId: sandboxSimulateCardAuthorizationAdvice + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the advice applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardAuthorizationAdviceRequest' + examples: + resizeUp: + summary: Re-size an open auth up to a new total of $20.00 + value: + cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 + amount: 2000 + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card or card transaction not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/credit_authorization_advice: + post: + summary: Simulate a card credit authorization advice + description: | + Simulate a network-initiated `CREDIT_AUTHORIZATION_ADVICE` against a card in the sandbox environment. Like `simulate/credit_authorization`, it is keyed by the card (PAN) and `merchant` rather than an existing transaction. Drives the same internal paths the card issuer would call in production. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + As with `simulate/authorization`, the decisioning outcome is controlled by the last three characters of `merchant.descriptor` — see the `simulate/authorization` suffix table. + + Production returns `404` on this path. + operationId: sandboxSimulateCardCreditAuthorizationAdvice + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the advice applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardAuthorizationRequest' + examples: + creditAdvice: + summary: $25.00 credit authorization advice + value: + amount: 2500 + currency: + code: USD + merchant: + descriptor: ACME MARKETPLACE + mcc: '5942' + country: US + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/return_reversal: + post: + summary: Simulate a card return reversal + description: | + Simulate a `RETURN_REVERSAL` against an existing `REFUNDED` card transaction in the sandbox environment — reversing a previously settled return. The parent transaction must be in `REFUNDED` state. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + Note: authorization reversal / void has no dedicated card-issuer simulate path (the void simulator emits a distinct `VOID` event), so — like authorization expiry — it is not exposed here. + + Production returns `404` on this path. + operationId: sandboxSimulateCardReturnReversal + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the return reversal applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardTransactionRefRequest' + examples: + returnReversal: + summary: Reverse a settled return on a refunded transaction + value: + cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 + responses: + '202': + description: Simulation accepted. The resulting card operation is delivered asynchronously via the issuer's events webhook. Returns the issuer transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardSimulationResponse' '400': description: Bad request - Invalid parameters content: @@ -20176,6 +20690,16 @@ components: $ref: '#/components/schemas/Currency' merchant: $ref: '#/components/schemas/CardMerchant' + SandboxCardSimulationResponse: + type: object + required: + - issuerTransactionToken + description: Response body for the sandbox card-event simulators. The simulate call pokes the card issuer's sandbox; the resulting card operation is delivered asynchronously via the issuer's events webhook, never synchronously in this response. + properties: + issuerTransactionToken: + type: string + description: The card issuer's transaction token for the simulated event. Correlates the eventual webhook-delivered card operation back to this simulate call. + example: f3a1c2d4-5b6e-7890-abcd-ef0123456789 SandboxCardClearingRequest: type: object required: @@ -20210,6 +20734,41 @@ components: description: Return amount in the smallest unit of the transaction's currency. Must be less than or equal to the net settled amount (settled minus previously-refunded). exclusiveMinimum: 0 example: 1500 + SandboxCardBalanceInquiryRequest: + type: object + required: + - merchant + description: Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/balance_inquiry`. Drives a balance-inquiry authorization against the card. A balance inquiry is always a `0`-amount authorization, so it carries no `amount`. + properties: + merchant: + $ref: '#/components/schemas/CardMerchant' + SandboxCardAuthorizationAdviceRequest: + type: object + required: + - cardTransactionId + - amount + description: Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/authorization_advice`. Drives an `AUTHORIZATION_ADVICE` that re-sizes an existing open authorization. + properties: + cardTransactionId: + type: string + description: The id of the `CardTransaction` the advice re-sizes. Must be in `AUTHORIZED` or `PARTIALLY_SETTLED` state. + example: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 + amount: + type: integer + format: int64 + description: The new *total* authorized amount, in the smallest unit of the transaction's currency, that the advice re-sizes the authorization to. + exclusiveMinimum: 0 + example: 2000 + SandboxCardTransactionRefRequest: + type: object + required: + - cardTransactionId + description: Sandbox-only request body for simulate endpoints keyed only by an existing card transaction — currently `POST /sandbox/cards/{id}/simulate/return_reversal`. + properties: + cardTransactionId: + type: string + description: The id of the `CardTransaction` to act against. + example: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 StablecoinProvider: type: string enum: diff --git a/openapi/components/schemas/cards/SandboxCardAuthorizationAdviceRequest.yaml b/openapi/components/schemas/cards/SandboxCardAuthorizationAdviceRequest.yaml new file mode 100644 index 000000000..45b05dcc8 --- /dev/null +++ b/openapi/components/schemas/cards/SandboxCardAuthorizationAdviceRequest.yaml @@ -0,0 +1,22 @@ +type: object +required: + - cardTransactionId + - amount +description: >- + Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/authorization_advice`. + Drives an `AUTHORIZATION_ADVICE` that re-sizes an existing open authorization. +properties: + cardTransactionId: + type: string + description: >- + The id of the `CardTransaction` the advice re-sizes. Must be in + `AUTHORIZED` or `PARTIALLY_SETTLED` state. + example: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 + amount: + type: integer + format: int64 + description: >- + The new *total* authorized amount, in the smallest unit of the + transaction's currency, that the advice re-sizes the authorization to. + exclusiveMinimum: 0 + example: 2000 diff --git a/openapi/components/schemas/cards/SandboxCardBalanceInquiryRequest.yaml b/openapi/components/schemas/cards/SandboxCardBalanceInquiryRequest.yaml new file mode 100644 index 000000000..1c0e9a9a2 --- /dev/null +++ b/openapi/components/schemas/cards/SandboxCardBalanceInquiryRequest.yaml @@ -0,0 +1,10 @@ +type: object +required: + - merchant +description: >- + Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/balance_inquiry`. + Drives a balance-inquiry authorization against the card. A balance inquiry is + always a `0`-amount authorization, so it carries no `amount`. +properties: + merchant: + $ref: ./CardMerchant.yaml diff --git a/openapi/components/schemas/cards/SandboxCardSimulationResponse.yaml b/openapi/components/schemas/cards/SandboxCardSimulationResponse.yaml new file mode 100644 index 000000000..04d799608 --- /dev/null +++ b/openapi/components/schemas/cards/SandboxCardSimulationResponse.yaml @@ -0,0 +1,15 @@ +type: object +required: + - issuerTransactionToken +description: >- + Response body for the sandbox card-event simulators. The simulate call pokes + the card issuer's sandbox; the resulting card operation is delivered + asynchronously via the issuer's events webhook, never synchronously in this + response. +properties: + issuerTransactionToken: + type: string + description: >- + The card issuer's transaction token for the simulated event. Correlates + the eventual webhook-delivered card operation back to this simulate call. + example: f3a1c2d4-5b6e-7890-abcd-ef0123456789 diff --git a/openapi/components/schemas/cards/SandboxCardTransactionRefRequest.yaml b/openapi/components/schemas/cards/SandboxCardTransactionRefRequest.yaml new file mode 100644 index 000000000..ba69a22ec --- /dev/null +++ b/openapi/components/schemas/cards/SandboxCardTransactionRefRequest.yaml @@ -0,0 +1,12 @@ +type: object +required: + - cardTransactionId +description: >- + Sandbox-only request body for simulate endpoints keyed only by an existing + card transaction — currently `POST /sandbox/cards/{id}/simulate/return_reversal`. +properties: + cardTransactionId: + type: string + description: >- + The id of the `CardTransaction` to act against. + example: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 39ada2584..f30e70628 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -304,6 +304,20 @@ paths: $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_clearing.yaml /sandbox/cards/{id}/simulate/return: $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml + /sandbox/cards/{id}/simulate/balance_inquiry: + $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_balance_inquiry.yaml + /sandbox/cards/{id}/simulate/credit_authorization: + $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_credit_authorization.yaml + /sandbox/cards/{id}/simulate/financial_authorization: + $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_financial_authorization.yaml + /sandbox/cards/{id}/simulate/financial_credit_authorization: + $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_financial_credit_authorization.yaml + /sandbox/cards/{id}/simulate/authorization_advice: + $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_advice.yaml + /sandbox/cards/{id}/simulate/credit_authorization_advice: + $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_credit_authorization_advice.yaml + /sandbox/cards/{id}/simulate/return_reversal: + $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml /stablecoin-provider-accounts: $ref: paths/stablecoins/stablecoin-provider-accounts.yaml /stablecoin-provider-accounts/{stablecoinProviderAccountId}: diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization.yaml index 3a36d5335..d24a76f80 100644 --- a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization.yaml +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization.yaml @@ -63,12 +63,15 @@ post: mcc: '5942' country: US responses: - '200': - description: Simulated authorization processed. Returns the resulting card transaction. + '202': + description: >- + Simulation accepted. The resulting card operation is delivered + asynchronously via the issuer's events webhook. Returns the issuer + transaction token that correlates the simulated event. content: application/json: schema: - $ref: ../../../components/schemas/cards/CardTransaction.yaml + $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml '400': description: Bad request - Invalid parameters content: diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_advice.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_advice.yaml new file mode 100644 index 000000000..f60a2df03 --- /dev/null +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_advice.yaml @@ -0,0 +1,77 @@ +post: + summary: Simulate a card authorization advice + description: > + Simulate an `AUTHORIZATION_ADVICE` that re-sizes an existing open + authorization on a `CardTransaction` in the sandbox environment. The + `amount` is the new *total* authorized amount the advice re-sizes to. The + parent transaction must be in `AUTHORIZED` or `PARTIALLY_SETTLED` state. The + resulting card operation is delivered asynchronously via the issuer's events + webhook. + + + Production returns `404` on this path. + operationId: sandboxSimulateCardAuthorizationAdvice + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the advice applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardAuthorizationAdviceRequest.yaml + examples: + resizeUp: + summary: Re-size an open auth up to a new total of $20.00 + value: + cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 + amount: 2000 + responses: + '202': + description: >- + Simulation accepted. The resulting card operation is delivered + asynchronously via the issuer's events webhook. Returns the issuer + transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error401.yaml + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error403.yaml + '404': + description: Card or card transaction not found + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error404.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_balance_inquiry.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_balance_inquiry.yaml new file mode 100644 index 000000000..7288ccd21 --- /dev/null +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_balance_inquiry.yaml @@ -0,0 +1,78 @@ +post: + summary: Simulate a card balance inquiry + description: > + Simulate a balance-inquiry authorization against a card in the sandbox + environment. A balance inquiry is always a `0`-amount authorization, so the + request carries no `amount` — only the `merchant`. Drives the same internal + paths the card issuer would call in production. The resulting card operation + is delivered asynchronously via the issuer's events webhook. + + + Production returns `404` on this path. + operationId: sandboxSimulateCardBalanceInquiry + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a balance inquiry against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardBalanceInquiryRequest.yaml + examples: + balanceInquiry: + summary: Balance inquiry at a fuel pump + value: + merchant: + descriptor: SHELL OIL 12345678 + mcc: '5541' + country: US + responses: + '202': + description: >- + Simulation accepted. The resulting card operation is delivered + asynchronously via the issuer's events webhook. Returns the issuer + transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error401.yaml + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error403.yaml + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error404.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_clearing.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_clearing.yaml index 501fcbf7f..8562657e2 100644 --- a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_clearing.yaml +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_clearing.yaml @@ -49,12 +49,15 @@ post: cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 amount: 0 responses: - '200': - description: Simulated clearing processed. Returns the updated card transaction. + '202': + description: >- + Simulation accepted. The resulting card operation is delivered + asynchronously via the issuer's events webhook. Returns the issuer + transaction token that correlates the simulated event. content: application/json: schema: - $ref: ../../../components/schemas/cards/CardTransaction.yaml + $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml '400': description: Bad request - Invalid parameters content: diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_credit_authorization.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_credit_authorization.yaml new file mode 100644 index 000000000..ebd6a8719 --- /dev/null +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_credit_authorization.yaml @@ -0,0 +1,86 @@ +post: + summary: Simulate a card credit authorization + description: > + Simulate an inbound credit authorization (a merchant-initiated credit to + the card, e.g. a refund pushed as an authorization) in the sandbox + environment. Drives the same internal paths the card issuer would call in + production. The resulting card operation is delivered asynchronously via the + issuer's events webhook. + + + As with `simulate/authorization`, the decisioning outcome is controlled by + the last three characters of `merchant.descriptor` — see the + `simulate/authorization` suffix table. + + + Production returns `404` on this path. + operationId: sandboxSimulateCardCreditAuthorization + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a credit authorization against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardAuthorizationRequest.yaml + examples: + creditAuth: + summary: $25.00 credit authorization + value: + amount: 2500 + currency: + code: USD + merchant: + descriptor: ACME MARKETPLACE + mcc: '5942' + country: US + responses: + '202': + description: >- + Simulation accepted. The resulting card operation is delivered + asynchronously via the issuer's events webhook. Returns the issuer + transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error401.yaml + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error403.yaml + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error404.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_credit_authorization_advice.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_credit_authorization_advice.yaml new file mode 100644 index 000000000..f4d50f32c --- /dev/null +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_credit_authorization_advice.yaml @@ -0,0 +1,87 @@ +post: + summary: Simulate a card credit authorization advice + description: > + Simulate a network-initiated `CREDIT_AUTHORIZATION_ADVICE` against a card in + the sandbox environment. Like `simulate/credit_authorization`, it is keyed + by the card (PAN) and `merchant` rather than an existing transaction. Drives + the same internal paths the card issuer would call in production. The + resulting card operation is delivered asynchronously via the issuer's events + webhook. + + + As with `simulate/authorization`, the decisioning outcome is controlled by + the last three characters of `merchant.descriptor` — see the + `simulate/authorization` suffix table. + + + Production returns `404` on this path. + operationId: sandboxSimulateCardCreditAuthorizationAdvice + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the advice applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardAuthorizationRequest.yaml + examples: + creditAdvice: + summary: $25.00 credit authorization advice + value: + amount: 2500 + currency: + code: USD + merchant: + descriptor: ACME MARKETPLACE + mcc: '5942' + country: US + responses: + '202': + description: >- + Simulation accepted. The resulting card operation is delivered + asynchronously via the issuer's events webhook. Returns the issuer + transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error401.yaml + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error403.yaml + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error404.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_financial_authorization.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_financial_authorization.yaml new file mode 100644 index 000000000..8e8a4a607 --- /dev/null +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_financial_authorization.yaml @@ -0,0 +1,87 @@ +post: + summary: Simulate a card financial authorization + description: > + Simulate a single-message financial authorization (an authorization that + clears in the same message, e.g. an ATM withdrawal or other + dual-message-exempt flow) against a card in the sandbox environment. Drives + the same internal paths the card issuer would call in production. The + resulting card operation is delivered asynchronously via the issuer's events + webhook. + + + As with `simulate/authorization`, the decisioning outcome is controlled by + the last three characters of `merchant.descriptor` — see the + `simulate/authorization` suffix table. + + + Production returns `404` on this path. + operationId: sandboxSimulateCardFinancialAuthorization + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a financial authorization against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardAuthorizationRequest.yaml + examples: + financialAuth: + summary: $80.00 single-message ATM withdrawal + value: + amount: 8000 + currency: + code: USD + merchant: + descriptor: ATM WITHDRAWAL 24TH ST + mcc: '6011' + country: US + responses: + '202': + description: >- + Simulation accepted. The resulting card operation is delivered + asynchronously via the issuer's events webhook. Returns the issuer + transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error401.yaml + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error403.yaml + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error404.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_financial_credit_authorization.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_financial_credit_authorization.yaml new file mode 100644 index 000000000..6132c1359 --- /dev/null +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_financial_credit_authorization.yaml @@ -0,0 +1,86 @@ +post: + summary: Simulate a card financial credit authorization + description: > + Simulate a single-message financial credit authorization (a credit to the + card that clears in the same message, e.g. an ATM deposit or push credit) + against a card in the sandbox environment. Drives the same internal paths + the card issuer would call in production. The resulting card operation is + delivered asynchronously via the issuer's events webhook. + + + As with `simulate/authorization`, the decisioning outcome is controlled by + the last three characters of `merchant.descriptor` — see the + `simulate/authorization` suffix table. + + + Production returns `404` on this path. + operationId: sandboxSimulateCardFinancialCreditAuthorization + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card to simulate a financial credit authorization against. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardAuthorizationRequest.yaml + examples: + financialCreditAuth: + summary: $40.00 single-message push credit + value: + amount: 4000 + currency: + code: USD + merchant: + descriptor: ACME PAYOUTS + mcc: '6012' + country: US + responses: + '202': + description: >- + Simulation accepted. The resulting card operation is delivered + asynchronously via the issuer's events webhook. Returns the issuer + transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error401.yaml + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error403.yaml + '404': + description: Card not found (also returned in production for this path) + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error404.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml index 6cf193c85..195fd41c9 100644 --- a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml @@ -34,12 +34,15 @@ post: cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 amount: 1500 responses: - '200': - description: Simulated return processed. Returns the updated card transaction. + '202': + description: >- + Simulation accepted. The resulting card operation is delivered + asynchronously via the issuer's events webhook. Returns the issuer + transaction token that correlates the simulated event. content: application/json: schema: - $ref: ../../../components/schemas/cards/CardTransaction.yaml + $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml '400': description: Bad request - Invalid parameters content: diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml new file mode 100644 index 000000000..030d87076 --- /dev/null +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_return_reversal.yaml @@ -0,0 +1,79 @@ +post: + summary: Simulate a card return reversal + description: > + Simulate a `RETURN_REVERSAL` against an existing `REFUNDED` card + transaction in the sandbox environment — reversing a previously settled + return. The parent transaction must be in `REFUNDED` state. The resulting + card operation is delivered asynchronously via the issuer's events webhook. + + + Note: authorization reversal / void has no dedicated card-issuer simulate + path (the void simulator emits a distinct `VOID` event), so — like + authorization expiry — it is not exposed here. + + + Production returns `404` on this path. + operationId: sandboxSimulateCardReturnReversal + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the return reversal applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardTransactionRefRequest.yaml + examples: + returnReversal: + summary: Reverse a settled return on a refunded transaction + value: + cardTransactionId: CardTransaction:019542f5-b3e7-1d02-0000-000000000100 + responses: + '202': + description: >- + Simulation accepted. The resulting card operation is delivered + asynchronously via the issuer's events webhook. Returns the issuer + transaction token that correlates the simulated event. + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error401.yaml + '403': + description: Forbidden - request was made with a production platform token + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error403.yaml + '404': + description: Card or card transaction not found + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error404.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error500.yaml