From 456cb11faa2836522217f0795fa029ae0f46aa2b Mon Sep 17 00:00:00 2001 From: Aaryaman Bhute Date: Wed, 16 Sep 2026 10:10:50 +0000 Subject: [PATCH] feat(sandbox): add the card correction simulate endpoint --- mintlify/openapi.yaml | 109 ++++++++++++++++++ openapi.yaml | 109 ++++++++++++++++++ .../cards/SandboxCardCorrectionRequest.yaml | 34 ++++++ openapi/openapi.yaml | 2 + ...andbox_cards_{id}_simulate_correction.yaml | 97 ++++++++++++++++ 5 files changed, 351 insertions(+) create mode 100644 openapi/components/schemas/cards/SandboxCardCorrectionRequest.yaml create mode 100644 openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_correction.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 487667dfa..9910a3846 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -9872,6 +9872,90 @@ paths: application/json: schema: $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/correction: + post: + summary: Simulate a card correction + description: | + Simulate a network correction against an existing settled card transaction in the sandbox environment — an adjustment the card network makes to money it has already moved. + + A `DEBIT` correction takes further funds from the cardholder and is permanent: nothing releases it and no capture settles against it. A `CREDIT` correction returns funds, the way a return does. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + Production returns `404` on this path. + operationId: sandboxSimulateCardCorrection + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the correction applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardCorrectionRequest' + examples: + correctionDebit: + summary: The network takes a further $2.50 on a settled purchase + value: + cardTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100 + amount: 250 + direction: DEBIT + correctionCredit: + summary: The network returns $2.50 it took in error + value: + cardTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100 + amount: 250 + direction: CREDIT + 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' + '409': + description: Conflict. The simulation targets a card in a program where the card issuer makes authorization decisions. These sandbox simulators support only card programs where Grid makes authorization decisions. This is a property of the card's program, so retrying will not help. + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' /sandbox/cards/{id}/simulate/authorization_reversal: post: summary: Simulate a card authorization reversal @@ -27845,6 +27929,31 @@ components: type: string description: The id of the `CardTransaction` to act against. example: Transaction:019542f5-b3e7-1d02-0000-000000000100 + SandboxCardCorrectionRequest: + type: object + required: + - cardTransactionId + - amount + - direction + description: Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/correction`. Posts a network correction against an existing settled `CardTransaction` — an adjustment the card network makes to money it has already moved. + properties: + cardTransactionId: + type: string + description: The id of the settled `CardTransaction` to correct. Must have at least one settled clearing. + example: Transaction:019542f5-b3e7-1d02-0000-000000000100 + amount: + type: integer + format: int64 + description: Correction amount in the smallest unit of the transaction's currency (cents for USD). Must not exceed the transaction's settled amount. + exclusiveMinimum: 0 + example: 250 + direction: + type: string + enum: + - DEBIT + - CREDIT + description: Which way the correction moves money. `DEBIT` takes further funds from the cardholder and is permanent — nothing releases it. `CREDIT` returns funds to the cardholder, the way a return does. + example: DEBIT SandboxCardReversalRequest: type: object required: diff --git a/openapi.yaml b/openapi.yaml index 487667dfa..9910a3846 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9872,6 +9872,90 @@ paths: application/json: schema: $ref: '#/components/schemas/Error500' + /sandbox/cards/{id}/simulate/correction: + post: + summary: Simulate a card correction + description: | + Simulate a network correction against an existing settled card transaction in the sandbox environment — an adjustment the card network makes to money it has already moved. + + A `DEBIT` correction takes further funds from the cardholder and is permanent: nothing releases it and no capture settles against it. A `CREDIT` correction returns funds, the way a return does. The resulting card operation is delivered asynchronously via the issuer's events webhook. + + Production returns `404` on this path. + operationId: sandboxSimulateCardCorrection + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the correction applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SandboxCardCorrectionRequest' + examples: + correctionDebit: + summary: The network takes a further $2.50 on a settled purchase + value: + cardTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100 + amount: 250 + direction: DEBIT + correctionCredit: + summary: The network returns $2.50 it took in error + value: + cardTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100 + amount: 250 + direction: CREDIT + 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' + '409': + description: Conflict. The simulation targets a card in a program where the card issuer makes authorization decisions. These sandbox simulators support only card programs where Grid makes authorization decisions. This is a property of the card's program, so retrying will not help. + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' /sandbox/cards/{id}/simulate/authorization_reversal: post: summary: Simulate a card authorization reversal @@ -27845,6 +27929,31 @@ components: type: string description: The id of the `CardTransaction` to act against. example: Transaction:019542f5-b3e7-1d02-0000-000000000100 + SandboxCardCorrectionRequest: + type: object + required: + - cardTransactionId + - amount + - direction + description: Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/correction`. Posts a network correction against an existing settled `CardTransaction` — an adjustment the card network makes to money it has already moved. + properties: + cardTransactionId: + type: string + description: The id of the settled `CardTransaction` to correct. Must have at least one settled clearing. + example: Transaction:019542f5-b3e7-1d02-0000-000000000100 + amount: + type: integer + format: int64 + description: Correction amount in the smallest unit of the transaction's currency (cents for USD). Must not exceed the transaction's settled amount. + exclusiveMinimum: 0 + example: 250 + direction: + type: string + enum: + - DEBIT + - CREDIT + description: Which way the correction moves money. `DEBIT` takes further funds from the cardholder and is permanent — nothing releases it. `CREDIT` returns funds to the cardholder, the way a return does. + example: DEBIT SandboxCardReversalRequest: type: object required: diff --git a/openapi/components/schemas/cards/SandboxCardCorrectionRequest.yaml b/openapi/components/schemas/cards/SandboxCardCorrectionRequest.yaml new file mode 100644 index 000000000..0f2bc0148 --- /dev/null +++ b/openapi/components/schemas/cards/SandboxCardCorrectionRequest.yaml @@ -0,0 +1,34 @@ +type: object +required: + - cardTransactionId + - amount + - direction +description: >- + Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/correction`. + Posts a network correction against an existing settled `CardTransaction` — an + adjustment the card network makes to money it has already moved. +properties: + cardTransactionId: + type: string + description: >- + The id of the settled `CardTransaction` to correct. Must have at least one + settled clearing. + example: Transaction:019542f5-b3e7-1d02-0000-000000000100 + amount: + type: integer + format: int64 + description: >- + Correction amount in the smallest unit of the transaction's currency + (cents for USD). Must not exceed the transaction's settled amount. + exclusiveMinimum: 0 + example: 250 + direction: + type: string + enum: + - DEBIT + - CREDIT + description: >- + Which way the correction moves money. `DEBIT` takes further funds from the + cardholder and is permanent — nothing releases it. `CREDIT` returns funds + to the cardholder, the way a return does. + example: DEBIT diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 954c592d6..2296b8c47 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -370,6 +370,8 @@ paths: $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 + /sandbox/cards/{id}/simulate/correction: + $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_correction.yaml /sandbox/cards/{id}/simulate/authorization_reversal: $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_authorization_reversal.yaml /sandbox/cards/{id}/simulate/authorization_expiry: diff --git a/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_correction.yaml b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_correction.yaml new file mode 100644 index 000000000..bb66be805 --- /dev/null +++ b/openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_correction.yaml @@ -0,0 +1,97 @@ +post: + summary: Simulate a card correction + description: > + Simulate a network correction against an existing settled card transaction + in the sandbox environment — an adjustment the card network makes to money + it has already moved. + + + A `DEBIT` correction takes further funds from the cardholder and is + permanent: nothing releases it and no capture settles against it. A `CREDIT` + correction returns funds, the way a return does. The resulting card + operation is delivered asynchronously via the issuer's events webhook. + + + Production returns `404` on this path. + operationId: sandboxSimulateCardCorrection + tags: + - Sandbox + security: + - BasicAuth: [] + parameters: + - name: id + in: path + required: true + description: The id of the card the correction applies to. + schema: + type: string + example: Card:019542f5-b3e7-1d02-0000-000000000010 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../../components/schemas/cards/SandboxCardCorrectionRequest.yaml + examples: + correctionDebit: + summary: The network takes a further $2.50 on a settled purchase + value: + cardTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100 + amount: 250 + direction: DEBIT + correctionCredit: + summary: The network returns $2.50 it took in error + value: + cardTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100 + amount: 250 + direction: CREDIT + 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 + '409': + description: >- + Conflict. The simulation targets a card in a program where the card + issuer makes authorization decisions. These sandbox simulators support + only card programs where Grid makes authorization decisions. This is a + property of the card's program, so retrying will not help. + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error409.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error500.yaml