{ "openapi": "3.1.0", "info": { "title": "Stitch API", "version": "1.0", "license": { "name": "Proprietary", "url": "https://stitch.money" } }, "servers": [ { "url": "https://api.stitch.money/v2" } ], "paths": { "/cards": { "get": { "summary": "List cards", "operationId": "listCards", "description": "List cards.", "parameters": [ { "name": "payerId", "in": "query", "required": true, "description": "The client-defined identifier for the payer whose cards should be listed.", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of cards to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of cards to skip for pagination.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Returns a paginated list of cards", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "The list of cards for this page.", "items": { "$ref": "#/components/schemas/Card" } }, "page": { "type": "object", "description": "Pagination information for this response.", "properties": { "limit": { "type": "integer", "description": "The limit used for this response." }, "offset": { "type": "integer", "description": "The offset used for this response." }, "hasNext": { "type": "boolean", "description": "Whether there is a next page for this response." } }, "required": [ "limit", "offset", "hasNext" ] } }, "required": [ "data", "page" ] } } } } }, "security": [ { "oauth": [ "client_card" ] } ] } }, "/terminal-sessions": { "get": { "summary": "List terminal sessions", "operationId": "listTerminalSessions", "description": "Lists terminal sessions.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "The page limit for this list response (0 to 50).", "schema": { "type": "integer", "minimum": 0, "maximum": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "The offset for pagination.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "externalReference", "in": "query", "required": false, "description": "Filter terminal sessions by external reference.", "schema": { "$ref": "#/components/schemas/ExternalReference" } }, { "name": "nonce", "in": "query", "required": false, "description": "Filter terminal sessions by nonce.", "schema": { "$ref": "#/components/schemas/Nonce" } } ], "responses": { "200": { "description": "Returns a paginated list of terminal sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "The list of terminal sessions for this page.", "items": { "$ref": "#/components/schemas/TerminalSession" } }, "page": { "type": "object", "description": "Pagination information for this response.", "properties": { "limit": { "type": "integer", "description": "The limit used for this response." }, "offset": { "type": "integer", "description": "The offset used for this response." }, "hasNext": { "type": "boolean", "description": "Whether there is a next page for this response." } }, "required": [ "limit", "offset", "hasNext" ] } }, "required": [ "data", "page" ] }, "examples": { "single": { "summary": "One terminal session", "value": { "data": [ { "id": "terminal_session_1234567890", "terminal": { "id": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "manufacturer": "sunmi", "model": "p2_se", "manufacturerSerialNumber": "PC08252T10208", "tid": "EP3567", "merchantId": "bWVyY2hhbnQvOTMzYTQwY2YtYjE5ZC00YWRmLTk4ZDgtNGRjZjVkY2Q4Yjll", "status": "active" }, "source": "api", "intent": { "charge": { "amount": 350.5, "currency": "ZAR" } }, "status": "success", "outcome": { "charge": { "id": "charge_1Q0PsIJvEtkwdCNYMSaVuRz6", "type": "in_person_card", "card": { "bin": "42424242", "last4": "4242", "expiry": { "month": 12, "year": 29 }, "network": "visa", "fundingType": "debit", "issuer": { "name": "standard bank", "country": "ZA" } }, "retrievalReferenceNumber": "1234567890", "networkTransactionIdentifier": "1234567890", "amount": 350.5, "currency": "ZAR", "status": "success", "metadata": { "example": "metadata" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" } }, "nonce": "9599a853-4333-4359-89de-658bfc86773a", "metadata": { "example": "metadata" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" } ], "page": { "limit": 10, "offset": 0, "hasNext": false } } } } } } } }, "security": [ { "oauth": [ "client_terminal_session" ] } ] }, "post": { "summary": "Create a terminal session", "operationId": "createTerminalSession", "description": "Creates a new terminal session to initiate a payment on a specified terminal device.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "intent": { "description": "Defines the purpose of the terminal session, such as processing a charge or a disbursement. Exactly one of `charge` or `disbursement` must be provided.", "oneOf": [ { "type": "object", "description": "A terminal session that processes a charge.", "properties": { "charge": { "type": "object", "description": "The charge to be processed during this terminal session.", "properties": { "amount": { "type": "number", "description": "The charge amount in the currency's major unit (e.g., 350.5 for R350.50)." }, "currency": { "type": "string", "description": "The charge currency in ISO 4217 format. Only \"ZAR\" is currently supported." }, "cashback": { "type": "object", "description": "Optional cashback to be dispensed to the customer in addition to the charge amount.", "properties": { "amount": { "type": "number", "description": "The cashback amount in the currency's major unit (e.g., 50.0 for R50.00)." }, "currency": { "type": "string", "description": "The cashback currency in ISO 4217 format. Only \"ZAR\" is currently supported." } } }, "capture": { "type": "object", "description": "Controls when the authorized payment is captured (i.e., when funds are settled).", "properties": { "method": { "type": "string", "description": "The capture method. `automatic` captures the payment immediately upon authorization. `manual` only authorizes the payment, requiring a separate capture request to settle the funds.", "enum": [ "automatic", "manual" ] } } } }, "required": [ "amount", "currency" ] } }, "required": [ "charge" ] }, { "type": "object", "description": "A terminal session that processes a disbursement.", "properties": { "disbursement": { "type": "object", "description": "The disbursement to be processed during this terminal session.", "properties": { "amount": { "type": "number", "description": "The disbursement amount in the currency's major unit (e.g., 150.0 for R150.00)." }, "currency": { "type": "string", "description": "The disbursement currency in ISO 4217 format. Only \"ZAR\" is currently supported." } }, "required": [ "amount", "currency" ] } }, "required": [ "disbursement" ] } ] }, "terminal": { "type": "string", "description": "The unique identifier of the terminal device where the payment should be processed" }, "nonce": { "$ref": "#/components/schemas/Nonce" }, "externalReference": { "$ref": "#/components/schemas/ExternalReference" }, "metadata": { "type": "object", "description": "Additional metadata to be associated with the terminal session.", "additionalProperties": true } }, "required": [ "intent", "terminal", "nonce" ] }, "examples": { "simpleCharge": { "summary": "Create a terminal session for a basic charge", "description": "This example creates a terminal session for a basic charge of R350.50.", "value": { "intent": { "charge": { "amount": 350.5, "currency": "ZAR" } }, "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "nonce": "9599a853-4333-4359-89de-658bfc86773a" } }, "chargeWithCashback": { "summary": "Create a terminal session for a charge with cashback", "description": "This example creates a terminal session for a charge of R350.50 with a cashback of R50.00 (total amount charged to the customer will be R400.50). The cashback will be dispensed to the customer in addition to the charge amount.", "value": { "intent": { "charge": { "amount": 350.5, "currency": "ZAR", "cashback": { "amount": 50, "currency": "ZAR" } } }, "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "nonce": "9599a853-4333-4359-89de-658bfc86773a" } }, "chargeWithManualCapture": { "summary": "Create a terminal session for a charge with manual capture", "description": "This example creates a terminal session for a charge of R350.50 with manual capture. The payment will be authorized but not captured immediately, requiring a separate capture request to settle the funds.", "value": { "intent": { "charge": { "amount": 350.5, "currency": "ZAR", "capture": { "method": "manual" } } }, "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "nonce": "9599a853-4333-4359-89de-658bfc86773a" } }, "simpleDisbursement": { "summary": "Create a terminal session for a disbursement", "description": "This example creates a terminal session for a disbursement of R150.00 to the customer.", "value": { "intent": { "disbursement": { "amount": 150, "currency": "ZAR" } }, "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "nonce": "b7e3f1a2-9c84-4d5e-a6b0-8f2d4e6c0a1b" } } } } } }, "responses": { "201": { "description": "Returns a new terminal session object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalSession" }, "examples": { "pending": { "$ref": "#/components/examples/PendingTerminalSession" } } } } } }, "security": [ { "oauth": [ "client_terminal_session" ] } ] } }, "/terminal-sessions/{id}": { "get": { "summary": "Get a terminal session", "operationId": "getTerminalSession", "description": "Retrieves a terminal session by its unique identifier.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the terminal session to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a terminal session object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalSession" }, "examples": { "successful": { "$ref": "#/components/examples/SuccessfulTerminalSession" }, "failed": { "$ref": "#/components/examples/FailedTerminalSession" }, "pending": { "$ref": "#/components/examples/PendingTerminalSession" } } } } } }, "security": [ { "oauth": [ "client_terminal_session" ] } ] } }, "/terminal-sessions/{id}/cancel": { "post": { "summary": "Cancel a terminal session", "operationId": "cancelTerminalSession", "description": "Cancel a terminal session. This will cancel the session on the terminal device.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the terminal session to cancel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a terminal session object. This call returns an error if the terminal session has already been completed (status is `success` or `failure`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalSession" }, "examples": { "successful": { "$ref": "#/components/examples/SuccessfulTerminalSession" }, "failed": { "$ref": "#/components/examples/FailedTerminalSession" }, "pending": { "$ref": "#/components/examples/PendingTerminalSession" } } } } } }, "security": [ { "oauth": [ "client_terminal_session" ] } ] } }, "/refunds": { "get": { "summary": "List refunds", "operationId": "listRefunds", "description": "Lists refunds for the authenticated client. Optionally filter by nonce, charge, or terminal session.", "parameters": [ { "name": "nonce", "in": "query", "required": false, "description": "Filter refunds by nonce.", "schema": { "$ref": "#/components/schemas/Nonce" } }, { "name": "charge", "in": "query", "required": false, "description": "Filter refunds by charge ID.", "schema": { "type": "string" } }, { "name": "terminalSession", "in": "query", "required": false, "description": "Filter refunds by the terminal session ID that produced the underlying charge.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of refunds to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of refunds to skip for pagination.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Returns a paginated list of refunds", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "The list of refunds for this page.", "items": { "$ref": "#/components/schemas/Refund" } }, "page": { "type": "object", "description": "Pagination information for this response.", "properties": { "limit": { "type": "integer", "description": "The limit used for this response." }, "offset": { "type": "integer", "description": "The offset used for this response." }, "hasNext": { "type": "boolean", "description": "Whether there is a next page for this response." } }, "required": [ "limit", "offset", "hasNext" ] } }, "required": [ "data", "page" ] } } } } }, "security": [ { "oauth": [ "client_refund" ] } ] }, "post": { "summary": "Create a refund", "operationId": "createRefund", "description": "Creates a new refund for a charge.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "charge": { "type": "string", "description": "The unique identifier of the charge to refund." }, "terminalSession": { "type": "string", "description": "The unique identifier of the terminal session to refund." }, "amount": { "type": "number", "description": "The refund amount in the currency's major unit (e.g., 30.0 for R30.00)." }, "currency": { "type": "string", "description": "The refund currency in ISO 4217 format. Only \"ZAR\" is currently supported.", "enum": [ "ZAR" ] }, "reason": { "type": "string", "description": "The reason for the refund.", "enum": [ "fraud", "requested_by_customer", "duplicate_charge" ] }, "nonce": { "$ref": "#/components/schemas/Nonce" }, "metadata": { "type": "object", "description": "Additional metadata to be associated with the refund.", "additionalProperties": true } }, "required": [ "amount", "currency", "reason", "nonce" ] }, "examples": { "basicRefund": { "summary": "Create a basic refund", "description": "This example creates a refund of R30.00 for a charge.", "value": { "charge": "charge_1Q0PsIJvEtkwdCNYMSaVuRz6", "amount": 30, "currency": "ZAR", "reason": "requested_by_customer", "nonce": "9599a853-4333-4359-89de-658bfc86773a" } } } } } }, "responses": { "201": { "description": "Returns a new refund object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "examples": { "successful": { "$ref": "#/components/examples/SuccessfulRefund" }, "failed": { "$ref": "#/components/examples/FailedRefund" } } } } } }, "security": [ { "oauth": [ "client_refund" ] } ] } }, "/refunds/{id}": { "get": { "summary": "Get a refund", "operationId": "getRefund", "description": "Retrieves a refund by its unique identifier.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the refund to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a refund object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "examples": { "successful": { "$ref": "#/components/examples/SuccessfulRefund" }, "failed": { "$ref": "#/components/examples/FailedRefund" } } } } } }, "security": [ { "oauth": [ "client_refund" ] } ] } }, "/cards/{id}": { "delete": { "summary": "Delete a card", "operationId": "deleteCard", "description": "Deletes a card stored on file.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The card identifier.", "schema": { "type": "string", "example": "Y2FyZC85YWY4OGE4MS05ZjNhLTRlNDItYWRiYy04ZTA1M2Q1YTM3M2U=" } } ], "responses": { "204": { "description": "The card was successfully deleted." } }, "security": [ { "oauth": [ "client_card" ] } ] } }, "/bank-account-verifications": { "post": { "summary": "Verify a bank account", "operationId": "verifyBankAccount", "description": "Verifies a bank account by checking that the account exists, is open, and that the account holder details match the provided identity information.\n\nThis service is available for South African bank accounts only. Identifying documents and business registrations default to South Africa (`ZA`) when `country` is omitted; explicit non-ZA values are passed through.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bankAccount": { "$ref": "#/components/schemas/BankAccount" }, "accountHolder": { "$ref": "#/components/schemas/BankAccountVerificationAccountHolder" } }, "required": [ "bankAccount", "accountHolder" ] }, "examples": { "individualWithIdDocument": { "summary": "Verify an individual with SA ID document", "value": { "bankAccount": { "bank": "fnb", "number": "1234567890", "type": "current" }, "accountHolder": { "type": "individual", "familyName": "Doe", "initials": "J", "identifyingDocument": { "type": "identity_document", "country": "ZA", "number": "9001015009087" } } } }, "individualWithPassport": { "summary": "Verify an individual with passport", "value": { "bankAccount": { "bank": "standard_bank", "number": "0987654321", "type": "savings" }, "accountHolder": { "type": "individual", "familyName": "Smith", "initials": "J", "identifyingDocument": { "type": "passport", "country": "GB", "number": "A12345678" } } } }, "business": { "summary": "Verify a business account", "value": { "bankAccount": { "bank": "absa", "number": "4056789012", "type": "current" }, "accountHolder": { "type": "business", "registrationNumber": "2020/123456/07", "country": "ZA", "name": "Acme Trading (Pty) Ltd" } } } } } } }, "responses": { "200": { "description": "Verification completed successfully. The response contains the verification results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountVerification" }, "examples": { "verifiedIndividualIdDocument": { "summary": "Verified individual with SA ID document", "value": { "id": "bav_1Q0PsIJvEtkwdCNYMSaVuR", "bankAccount": { "bank": "fnb", "branchCode": "250655", "number": "1234567890", "type": "current" }, "accountHolder": { "type": "individual", "familyName": "Doe", "initials": "J", "identifyingDocument": { "type": "identity_document", "country": "ZA", "number": "9001015009087" } }, "verificationResult": { "outcome": "verified", "bankAccount": { "exists": "verified", "typeMatch": "verified", "isOpen": true, "isOpenForMoreThanThreeMonths": true, "acceptsDebits": true, "acceptsCredits": true }, "accountHolder": { "identifyingDocument": "verified", "familyName": "verified", "initials": "verified" } }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" } }, "verifiedIndividualPassport": { "summary": "Verified individual with passport", "value": { "id": "bav_5GhJk2mNqPrZ9aWcde4HIJ", "bankAccount": { "bank": "standard_bank", "branchCode": "051001", "number": "0987654321", "type": "savings" }, "accountHolder": { "type": "individual", "familyName": "Smith", "initials": "J", "identifyingDocument": { "type": "passport", "country": "GB", "number": "A12345678" } }, "verificationResult": { "outcome": "verified", "bankAccount": { "exists": "verified", "typeMatch": "verified", "isOpen": true, "isOpenForMoreThanThreeMonths": true, "acceptsDebits": true, "acceptsCredits": true }, "accountHolder": { "identifyingDocument": "verified", "familyName": "verified", "initials": "verified" } }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" } }, "verifiedBusiness": { "summary": "Verified business account", "value": { "id": "bav_2eyfk4nQpHs7iWQ4QwjJK5", "bankAccount": { "bank": "absa", "branchCode": "632005", "number": "4056789012", "type": "current" }, "accountHolder": { "type": "business", "registrationNumber": "2020/123456/07", "country": "ZA", "name": "Acme Trading (Pty) Ltd" }, "verificationResult": { "outcome": "verified", "bankAccount": { "exists": "verified", "typeMatch": "verified", "isOpen": true, "isOpenForMoreThanThreeMonths": true, "acceptsDebits": true, "acceptsCredits": true }, "accountHolder": { "registrationNumber": "verified", "name": "verified" } }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" } }, "refutedIndividualNameMismatch": { "summary": "Refuted individual account (name mismatch)", "value": { "id": "bav_3RxGl8mTuSqXyZ1abc2DEF", "bankAccount": { "bank": "capitec", "branchCode": "470010", "number": "1234567890", "type": "savings" }, "accountHolder": { "type": "individual", "familyName": "Doe", "initials": "J", "identifyingDocument": { "type": "identity_document", "country": "ZA", "number": "9001015009087" } }, "verificationResult": { "outcome": "refuted", "bankAccount": { "exists": "verified", "typeMatch": "verified", "isOpen": true, "isOpenForMoreThanThreeMonths": true, "acceptsDebits": true, "acceptsCredits": true }, "accountHolder": { "identifyingDocument": "verified", "familyName": "refuted", "initials": "verified" } }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" } }, "refutedAccountClosed": { "summary": "Refuted (account closed) — verdicts pass but bank facts say closed", "value": { "id": "bav_6KkLm3oPqRsT0bYdef5KLM", "bankAccount": { "bank": "fnb", "branchCode": "250655", "number": "1234567890", "type": "current" }, "accountHolder": { "type": "individual", "familyName": "Doe", "initials": "J", "identifyingDocument": { "type": "identity_document", "country": "ZA", "number": "9001015009087" } }, "verificationResult": { "outcome": "refuted", "bankAccount": { "exists": "verified", "typeMatch": "verified", "isOpen": false, "isOpenForMoreThanThreeMonths": false, "acceptsDebits": false, "acceptsCredits": false }, "accountHolder": { "identifyingDocument": "verified", "familyName": "verified", "initials": "verified" } }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" } }, "indeterminateIndividual": { "summary": "Indeterminate result (bank could not perform the check)", "value": { "id": "bav_4SyHm9nUvTrYzA2cde3FGH", "bankAccount": { "bank": "za_albaraka_bank", "branchCode": "800000", "number": "5678901234", "type": "current" }, "accountHolder": { "type": "individual", "familyName": "Doe", "initials": "J", "identifyingDocument": { "type": "identity_document", "country": "ZA", "number": "9001015009087" } }, "verificationResult": { "outcome": "indeterminate", "bankAccount": { "exists": "indeterminate", "typeMatch": "indeterminate", "isOpen": null, "isOpenForMoreThanThreeMonths": null, "acceptsDebits": null, "acceptsCredits": null }, "accountHolder": { "identifyingDocument": "indeterminate", "familyName": "indeterminate", "initials": "indeterminate" } }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" } } } } } }, "202": { "description": "Verification is in progress. Resubmit the same request to check for results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ], "description": "Indicates the verification is still in progress." }, "message": { "type": "string", "description": "A human-readable status message." } }, "required": [ "status", "message" ] }, "example": { "status": "pending", "message": "Verification is in progress. Resubmit the same request to check for results." } } } }, "400": { "description": "Bad request. The request body is malformed or fails schema validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "code": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "title", "code", "detail" ] }, "example": { "title": "Invalid Input", "code": "BAD_USER_INPUT", "detail": "Invalid request body: bankAccount.number is required" } } } }, "401": { "description": "Unauthorized. The access token is missing, expired, or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "code": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "title", "code", "detail" ] }, "example": { "title": "Unauthorized", "code": "UNAUTHORIZED", "detail": "The Authorization header is missing or contains an invalid/expired token" } } } }, "403": { "description": "Forbidden. The access token does not have the required scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "code": { "type": "string" }, "detail": { "type": "string" }, "missingScopes": { "type": "array", "description": "The OAuth scopes that the token is missing and that are required to access this resource.", "items": { "type": "string" } } }, "required": [ "title", "code", "detail" ] }, "example": { "title": "Forbidden", "code": "FORBIDDEN", "detail": "The provided authorization token does not include the required scopes to access this resource", "missingScopes": [ "accountholders" ] } } } }, "422": { "description": "Verification error. The request was valid but the verification could not be completed due to a business logic error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The error title." }, "code": { "type": "string", "description": "The error code." }, "detail": { "type": "string", "description": "A human-readable error message." }, "reason": { "type": [ "string", "null" ], "description": "The specific reason the verification failed." } }, "required": [ "title", "code", "detail" ] }, "example": { "title": "Verification Error", "code": "VERIFICATION_ERROR", "detail": "The provided account number is not valid at the selected bank.", "reason": "invalid_account_number" } } } }, "503": { "description": "Service unavailable. The verification service is temporarily unavailable for maintenance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "code": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "title", "code", "detail" ] }, "example": { "title": "Service Unavailable", "code": "SERVICE_UNAVAILABLE", "detail": "Bank account verification is temporarily unavailable." } } } } }, "security": [ { "oauth": [ "client_bankaccountverification", "accountholders" ] } ] } }, "/files": { "post": { "summary": "Upload a dispute evidence file", "operationId": "uploadDisputeEvidenceFile", "description": "Uploads one file for later dispute evidence submission. The upload records the supplied case reference without calling the dispute case system. Any MIME type is accepted, up to 50 MiB per file.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "additionalProperties": false, "required": [ "file", "type", "caseReference", "evidenceType" ], "properties": { "file": { "type": "string", "format": "binary" }, "type": { "type": "string", "const": "dispute_evidence" }, "caseReference": { "type": "string", "minLength": 1, "maxLength": 255 }, "evidenceType": { "type": "string", "const": "consolidated" } } } } } }, "responses": { "201": { "description": "File uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeEvidenceFile" } } } }, "400": { "description": "Invalid multipart fields or multipart parsing failure. Parser-level failures, including files over 50 MiB, return text/plain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string", "example": "Invalid request body format" } } } }, "401": { "description": "Missing, expired, or invalid access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The token lacks the client_file_management scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "oauth": [ "client_file_management" ] } ] } }, "/fingerprint/events": { "get": { "summary": "List fingerprint events", "operationId": "listFingerprintEvents", "description": "Lists fingerprint events for the authenticated client. Pass exactly one of correlationId or deviceId. Results are newest first.", "parameters": [ { "name": "correlationId", "in": "query", "required": false, "description": "Filter events by the business reference sent on submit.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "deviceId", "in": "query", "required": false, "description": "Filter events by public device id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of events to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of events to skip for pagination.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Page of fingerprint events.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FingerprintEvent" } }, "page": { "type": "object", "additionalProperties": false, "required": [ "limit", "offset", "hasNext" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasNext": { "type": "boolean" } } } } } } } }, "400": { "description": "Missing filter, both filters, or invalid pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, expired, or invalid access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The token lacks the client_fingerprinting scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "oauth": [ "client_fingerprinting" ] } ] }, "post": { "summary": "Submit a fingerprint event", "operationId": "submitFingerprintEvent", "description": "Submits an SDK fingerprint payload and returns a client-scoped device id with curated signals. The OAuth client id is taken from the access token. clientId is not a request field. Safe retries of the same request use the standard Idempotency-Key header.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Key used to make retry requests safe.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "fingerprint" ], "properties": { "fingerprint": { "type": "string", "minLength": 1, "description": "Opaque base64 payload returned by the Stitch SDK." }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional business reference for logs and support. Not an idempotency key." }, "userId": { "type": "string", "minLength": 1, "description": "Optional merchant user identifier. Not used for matching." }, "metadata": { "$ref": "#/components/schemas/FingerprintMetadata" } } }, "examples": { "login": { "summary": "Submit a login fingerprint", "value": { "correlationId": "login-123", "userId": "user-abc", "fingerprint": "base64-sdk-payload", "metadata": { "action": "login", "channel": "my-app-web" } } } } } } }, "responses": { "200": { "description": "Fingerprint event resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FingerprintEvent" } } } }, "400": { "description": "Invalid request body or idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, expired, or invalid access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The token lacks the client_fingerprinting scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "oauth": [ "client_fingerprinting" ] } ] } }, "/fingerprint/events/{id}": { "get": { "summary": "Get a fingerprint event", "operationId": "getFingerprintEvent", "description": "Re-fetches a completed fingerprint event by its public id.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public fingerprint event id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fingerprint event found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FingerprintEvent" } } } }, "400": { "description": "Invalid event id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, expired, or invalid access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The token lacks the client_fingerprinting scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "404": { "description": "Unknown event id, or not owned by this client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "oauth": [ "client_fingerprinting" ] } ] } }, "/fingerprint/devices/{id}": { "get": { "summary": "Get a fingerprint device", "operationId": "getFingerprintDevice", "description": "Returns the device resource for a public device id. Signals may be omitted when a snapshot is unavailable.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public fingerprint device id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Device known.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FingerprintDevice" } } } }, "400": { "description": "Invalid device id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, expired, or invalid access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The token lacks the client_fingerprinting scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "404": { "description": "Unknown device id, or not owned by this client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "oauth": [ "client_fingerprinting" ] } ] } }, "/disputes/{caseReference}/evidence": { "post": { "summary": "Submit dispute evidence", "operationId": "submitDisputeEvidence", "description": "Atomically submits previously uploaded files as evidence for the dispute. The path is the only source of caseReference. Retries using the same path, nonce, and exact request body return the original 201 response. After a 500, retry with the same nonce; do not rotate it.", "parameters": [ { "name": "caseReference", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "nonce", "fileIds" ], "properties": { "nonce": { "type": "string", "minLength": 1, "maxLength": 255 }, "fileIds": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string" } }, "submittedBy": { "type": "string", "minLength": 1, "maxLength": 255 }, "comments": { "type": "string", "minLength": 1, "maxLength": 5000 } } }, "example": { "nonce": "d290f1ee-6c54-4b01-90e6-d701748f0851", "fileIds": [ "file_2xKq9mNpLr8ZtWvYbCdEfG" ], "submittedBy": "disputes@amazon.com", "comments": "All requested documentation attached." } } } }, "responses": { "201": { "description": "Evidence received, including an exact idempotent replay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeEvidenceSubmission" } } } }, "400": { "description": "Malformed fields or invalid file IDs. Parser-level failures, including malformed JSON, return text/plain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string", "example": "Invalid request body format" } } } }, "401": { "description": "Missing, expired, or invalid access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The token lacks the client_evidence_submission scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" } } } }, "404": { "description": "The case is missing or not owned by the authenticated client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency conflict, or a concurrent identical submission still in progress. Sequential retries of the same nonce wait for a terminal 201 or 500 rather than poll this status.", "headers": { "Retry-After": { "description": "Seconds before retrying a concurrent in-progress identical request.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The evidence deadline has passed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The case cannot accept evidence in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Unexpected server failure; retry with the same nonce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "oauth": [ "client_evidence_submission" ] } ] } } }, "webhooks": { "terminal-session.success": { "post": { "summary": "Terminal session success event", "operationId": "terminalSessionSuccessWebhook", "description": "Sent when a terminal session has been completed successfully (status is `success`).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "terminal-session.success" ] }, "data": { "$ref": "#/components/schemas/TerminalSession" } } } ] }, "examples": { "successful": { "$ref": "#/components/examples/TerminalSessionSuccessWebhookEvent" }, "successfulDisbursement": { "$ref": "#/components/examples/TerminalSessionDisbursementSuccessWebhookEvent" }, "successfulRefund": { "$ref": "#/components/examples/TerminalSessionRefundSuccessWebhookEvent" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "terminal-session.failure": { "post": { "summary": "Terminal session failure event", "operationId": "terminalSessionFailureWebhook", "description": "Sent when a terminal session has been completed unsuccessfully (status is `failure`).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "terminal-session.failure" ] }, "data": { "$ref": "#/components/schemas/TerminalSession" } } } ] }, "examples": { "failed": { "$ref": "#/components/examples/TerminalSessionFailureWebhookEvent" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } } }, "components": { "securitySchemes": { "oauth": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://secure.stitch.money/connect/token", "scopes": { "client_card": "Fetch, list, and delete cards", "client_terminal_session": "Create/Fetch/Cancel a terminal session", "client_refund": "Create/Fetch/List refunds", "client_bankaccountverification": "Verify bank account details", "client_file_management": "Upload and manage client files", "client_evidence_submission": "Submit files as dispute evidence", "client_fingerprinting": "Submit and read device fingerprint events" } } } } }, "schemas": { "CardMetadata": { "type": "object", "properties": { "bin": { "type": "string", "description": "The first 8 digits of the card number." }, "last4": { "type": "string", "description": "The last 4 digits of the card number." }, "expiry": { "type": "object", "properties": { "month": { "type": "string", "description": "The expiry month of the card in MM format (01-12)." }, "year": { "type": "string", "description": "The expiry year of the card in YY format (e.g., 25 for 2025)." } }, "required": [ "month", "year" ] }, "network": { "type": "string", "description": "The network of the card.", "enum": [ "visa", "mastercard", "amex", "diners" ] }, "fundingType": { "type": "string", "description": "The funding type of the card.", "enum": [ "credit", "debit", "prepaid" ] }, "issuer": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the financial institution that issued the card." }, "country": { "type": "string", "description": "The country code (ISO 3166-1 alpha-2) of the card issuer (e.g., \"ZA\" for South Africa)." } } } }, "required": [ "bin", "last4", "expiry" ], "example": { "bin": "42424242", "last4": "4242", "expiry": { "month": "12", "year": "29" }, "network": "visa", "fundingType": "debit", "issuer": { "name": "standard_bank", "country": "ZA" } } }, "Card": { "allOf": [ { "$ref": "#/components/schemas/CardMetadata" }, { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this card.", "example": "Y2FyZC82N2NlMTY5Mi1kMWQ3LTQ5NDAtYWVlNC1iMTE5MTk0M2NjYzQ=" }, "createdAt": { "type": "string", "description": "The UTC timestamp indicating when the card was created. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:30:00Z).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The UTC timestamp indicating when the card was last modified. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:35:00Z).", "format": "date-time" } }, "required": [ "id", "createdAt" ] } ], "example": { "id": "Y2FyZC82N2NlMTY5Mi1kMWQ3LTQ5NDAtYWVlNC1iMTE5MTk0M2NjYzQ=", "bin": "42424242", "last4": "4242", "expiry": { "month": "12", "year": "29" }, "network": "visa", "fundingType": "debit", "issuer": { "name": "standard_bank", "country": "ZA" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" } }, "ExternalReference": { "type": "string", "description": "A custom identifier that you can use to reference this resource in your own system. Multiple resources can share the same external reference, so this is not enforced as unique." }, "Nonce": { "type": "string", "description": "A unique identifier for this specific resource. Use the nonce to ensure idempotency. If you attempt to create a resource with a nonce that has already been used, an error will be returned." }, "IdentifyingDocument": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of identifying document.", "enum": [ "identity_document", "passport", "temporary_residence" ] }, "country": { "type": "string", "description": "Country code of the document, in ISO 3166-1 alpha-2 format (e.g., ZA)." }, "number": { "type": "string", "description": "The document number." } } }, "Customer": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the customer." }, "email": { "type": "string", "description": "The email of the customer." }, "phone": { "type": "string", "description": "The phone number of the customer, including country code (e.g., +27612345678)." }, "identifyingDocument": { "$ref": "#/components/schemas/IdentifyingDocument" }, "externalReference": { "type": "string", "description": "A custom identifier that you use to reference this customer in your own system." } } }, "Metadata": { "type": "object", "description": "A set of key-value pairs that you can attach to the resource. Use metadata to store additional, structured information relevant to your integration.", "additionalProperties": true }, "Charge": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this charge." }, "amount": { "type": "number", "description": "The amount to be charged in the currency's major unit (e.g., 350.5 for R350.50)." }, "currency": { "type": "string", "description": "The charge currency in ISO 4217 format. Only \"ZAR\" is currently supported." }, "status": { "type": "string", "description": "The current status of the charge. `processing` indicates the charge is being processed, `requires_capture` indicates the charge requires a capture request to settle the funds, `requires_interaction` indicates the charge requires a manual interaction from the customer, `success` indicates the charge was processed successfully, `failure` indicates the charge did not complete successfully, and `cancelled` indicates the charge was cancelled.", "enum": [ "processing", "requires_capture", "requires_interaction", "success", "failure", "cancelled" ] }, "nonce": { "$ref": "#/components/schemas/Nonce" }, "externalReference": { "$ref": "#/components/schemas/ExternalReference" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "createdAt": { "type": "string", "description": "The UTC timestamp indicating when the charge was created. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:30:00Z).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The UTC timestamp indicating when the charge was last modified, such as when the status changes. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:35:00Z).", "format": "date-time" } }, "required": [ "id", "amount", "currency", "status", "metadata", "createdAt", "updatedAt" ] }, "InPersonCardCharge": { "allOf": [ { "$ref": "#/components/schemas/Charge" }, { "type": "object", "properties": { "type": { "type": "string", "description": "The type of charge. For in-person card charges, this is always `in_person_card`.", "enum": [ "in_person_card" ] }, "card": { "$ref": "#/components/schemas/CardMetadata" }, "cashback": { "type": "object", "description": "Cashback dispensed to the customer in addition to the charge amount.", "properties": { "amount": { "type": "object", "properties": { "quantity": { "type": "number", "description": "The cashback amount in the currency's major unit." }, "currency": { "type": "string", "description": "The currency in ISO 4217 format.", "enum": [ "ZAR" ] } }, "required": [ "quantity", "currency" ] } }, "required": [ "amount" ] }, "retrievalReferenceNumber": { "type": "string", "description": "The retrieval reference number (RRN) assigned by the card network for this transaction." }, "networkTransactionIdentifier": { "type": "string", "description": "The network transaction identifier assigned by the card network." }, "failure": { "type": "object", "description": "Details about the failure. Only present when the charge status is `failure`.", "properties": { "reason": { "type": "string", "description": "The reason for the failure.", "enum": [ "authorization_failed" ] }, "resultCode": { "type": "object", "description": "The result code from the card network. This is only present when the failure reason is `authorization_failed`.", "properties": { "value": { "type": "string", "description": "The numeric result code value.", "example": "05" }, "descriptor": { "type": "string", "description": "A machine-readable descriptor for the result code.", "example": "do_not_honour" }, "detail": { "type": "string", "description": "A human-readable explanation of the result code.", "example": "Do Not Honour indicates that the card issuer declined the transaction without providing a specific reason. The cardholder should contact their bank for more information." } }, "required": [ "value", "descriptor", "detail" ] } }, "required": [ "reason" ] } }, "required": [ "type", "card", "retrievalReferenceNumber" ] } ] }, "InPersonCardDisbursement": { "allOf": [ { "$ref": "#/components/schemas/Charge" }, { "type": "object", "properties": { "type": { "type": "string", "description": "The type of disbursement. For in-person card disbursements, this is always `in_person_card`.", "enum": [ "in_person_card" ] }, "card": { "$ref": "#/components/schemas/CardMetadata" }, "retrievalReferenceNumber": { "type": "string", "description": "The retrieval reference number (RRN) assigned by the card network for this transaction." }, "networkTransactionIdentifier": { "type": "string", "description": "The network transaction identifier assigned by the card network." } }, "required": [ "type", "card", "retrievalReferenceNumber" ] } ] }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this refund." }, "type": { "type": "string", "description": "The type of refund.", "enum": [ "card", "in_person_card" ] }, "charge": { "type": "string", "description": "The unique identifier of the charge being refunded." }, "amount": { "type": "number", "description": "The refund amount in the currency's major unit (e.g., 30.0 for R30.00)." }, "currency": { "type": "string", "description": "The refund currency in ISO 4217 format. Only \"ZAR\" is currently supported.", "enum": [ "ZAR" ] }, "reason": { "type": "string", "description": "The reason for the refund.", "enum": [ "fraud", "requested_by_customer", "duplicate_charge" ] }, "status": { "type": "string", "description": "The current status of the refund. `processing` indicates the refund is being processed, `success` indicates the refund was processed successfully, `paused` indicates the refund is paused pending resolution, and `failure` indicates the refund did not complete successfully.", "enum": [ "processing", "success", "paused", "failure" ] }, "nonce": { "$ref": "#/components/schemas/Nonce" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "createdAt": { "type": "string", "description": "The UTC timestamp indicating when the refund was created. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:30:00Z).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The UTC timestamp indicating when the refund was last modified, such as when the status changes. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:35:00Z).", "format": "date-time" } }, "required": [ "id", "charge", "amount", "currency", "reason", "status", "nonce", "createdAt", "updatedAt" ] }, "TerminalSession": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this terminal session." }, "terminal": { "type": "string", "description": "The terminal unique identifier." }, "source": { "type": "string", "description": "The channel that created the terminal session. `api` indicates the REST API, `standalone_app` indicates the standalone terminal app, and `sdk` indicates the Terminal SDK.", "enum": [ "api", "standalone_app", "sdk" ] }, "intent": { "description": "Defines the purpose of the terminal session, such as processing a charge, disbursement, or refund. Exactly one of `charge`, `disbursement`, or `refund` will be present.", "oneOf": [ { "type": "object", "description": "A terminal session that processes a charge.", "properties": { "charge": { "type": "object", "description": "The charge to be processed during this terminal session.", "properties": { "amount": { "type": "number", "description": "The charge amount in the currency's major unit (e.g., 350.5 for R350.50)." }, "currency": { "type": "string", "description": "The charge currency in ISO 4217 format. Only \"ZAR\" is currently supported." }, "cashback": { "type": "object", "description": "Optional cashback to be dispensed to the customer in addition to the charge amount.", "properties": { "amount": { "type": "number", "description": "The cashback amount in the currency's major unit (e.g., 50.0 for R50.00)." }, "currency": { "type": "string", "description": "The cashback currency in ISO 4217 format. Only \"ZAR\" is currently supported." } } } }, "required": [ "amount", "currency" ] } }, "required": [ "charge" ] }, { "type": "object", "description": "A terminal session that processes a disbursement.", "properties": { "disbursement": { "type": "object", "description": "The disbursement to be processed during this terminal session.", "properties": { "amount": { "type": "number", "description": "The disbursement amount in the currency's major unit (e.g., 150.0 for R150.00)." }, "currency": { "type": "string", "description": "The disbursement currency in ISO 4217 format. Only \"ZAR\" is currently supported." } }, "required": [ "amount", "currency" ] } }, "required": [ "disbursement" ] }, { "type": "object", "description": "A terminal session that processes a refund.", "properties": { "refund": { "type": "object", "description": "The refund to be processed during this terminal session.", "properties": { "terminalSession": { "type": "string", "description": "The original terminal session unique identifier." }, "amount": { "type": "number", "description": "The refund amount in the currency's major unit (e.g., 45.0 for R45.00)." }, "currency": { "type": "string", "description": "The refund currency in ISO 4217 format. Only \"ZAR\" is currently supported." }, "reason": { "type": "string", "description": "The reason for the refund.", "enum": [ "fraud", "requested_by_customer", "duplicate_charge" ] } }, "required": [ "terminalSession", "amount", "currency", "reason" ] } }, "required": [ "refund" ] } ] }, "customer": { "$ref": "#/components/schemas/Customer" }, "status": { "type": "string", "description": "The current status of the terminal session. `pending` indicates the session is awaiting completion on the terminal, `success` indicates the payment was processed successfully, and `failure` indicates the session did not complete successfully.", "enum": [ "pending", "success", "failure" ] }, "failureReason": { "type": "string", "description": "The reason the terminal session failed. Only present when the status is `failure`. Possible values are `expired` (session timed out), `cancelled_by_terminal` (operator cancelled on the device), `cancelled_by_api` (cancelled via API request), `offline_terminal` (terminal was not connected), `busy_terminal` (terminal was processing another session), or `attempt_limit_exceeded` (maximum number of failed attempts for this terminal session reached).", "enum": [ "expired", "cancelled_by_terminal", "cancelled_by_api", "offline_terminal", "busy_terminal", "attempt_limit_exceeded" ] }, "outcome": { "description": "The outcome of the terminal session. This is only present when the status is `success`. Contains either a `charge`, `disbursement`, or `refund` matching the session intent. Exactly one of `charge`, `disbursement`, or `refund` will be present.", "oneOf": [ { "type": "object", "description": "The outcome of a terminal session that processed a charge.", "properties": { "charge": { "$ref": "#/components/schemas/InPersonCardCharge" } }, "required": [ "charge" ] }, { "type": "object", "description": "The outcome of a terminal session that processed a disbursement.", "properties": { "disbursement": { "$ref": "#/components/schemas/InPersonCardDisbursement" } }, "required": [ "disbursement" ] }, { "type": "object", "description": "The outcome of a terminal session that processed a refund.", "properties": { "refund": { "$ref": "#/components/schemas/Refund" } }, "required": [ "refund" ] } ] }, "nonce": { "$ref": "#/components/schemas/Nonce" }, "externalReference": { "$ref": "#/components/schemas/ExternalReference" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "createdAt": { "type": "string", "description": "The UTC timestamp indicating when the terminal session was created. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:30:00Z).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The UTC timestamp indicating when the terminal session was last modified, such as when the status changes. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:35:00Z).", "format": "date-time" } }, "required": [ "id", "terminal", "source", "intent", "status", "nonce", "metadata", "createdAt", "updatedAt" ] }, "BankAccount": { "type": "object", "description": "The bank account being verified. `bank` is required. `branchCode` is optional; when omitted the corresponding universal branch code for the supplied `bank` is used.", "additionalProperties": false, "properties": { "bank": { "type": "string", "description": "The bank where the account is held. Required. This is an enum of supported South African banks (it is not an opaque identifier).", "enum": [ "absa", "african_bank", "capitec", "discovery_bank", "fnb", "grindrod_bank", "investec", "nedbank", "sasfin_bank", "standard_bank", "za_bidvest", "tymebank", "za_access_bank", "za_albaraka_bank", "za_bank_zero", "za_standard_chartered_bank" ] }, "branchCode": { "type": "string", "description": "The 6-digit branch code. Optional. When omitted, the universal branch code for the supplied `bank` is used. Supply this when you want to verify against a specific branch.", "pattern": "^\\d{6}$" }, "number": { "type": "string", "description": "The bank account number to verify. Numeric digits only, 6–13 characters.", "pattern": "^\\d+$", "minLength": 6, "maxLength": 13 }, "type": { "type": "string", "description": "The type of bank account. Mirrors the upstream `AccountType` enum; `credit` and `investment` are accepted for parity with the GraphQL contract.", "enum": [ "current", "savings", "credit", "loan", "investment", "other", "unknown" ] } }, "required": [ "bank", "number" ] }, "BankAccountVerificationAccountHolder": { "type": "object", "description": "The account holder details to verify against. The `type` discriminator selects whether this is an individual or a business. Business verification is for South African registered businesses only.", "discriminator": { "propertyName": "type" }, "oneOf": [ { "type": "object", "description": "An individual account holder.", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "individual" ], "description": "The account holder type." }, "familyName": { "type": "string", "description": "Surname or family name of the individual.", "maxLength": 60 }, "initials": { "type": "string", "description": "Initials of the account holder (e.g. \"JP\" for Jonathan Paul).", "maxLength": 5 }, "phone": { "type": "string", "description": "Phone number to verify against the account holder details, if available." }, "email": { "type": "string", "format": "email", "description": "Email address to verify against the account holder details, if available." }, "identifyingDocument": { "type": "object", "description": "The identifying document for the individual. The `country` field is an ISO 3166-1 alpha-2 code and defaults to `ZA` because BAVS today is a South African–only service; the field is exposed for forward compatibility and parity with the upstream `CountryCode` contract.", "additionalProperties": false, "properties": { "type": { "type": "string", "description": "The type of identifying document.", "enum": [ "identity_document", "passport" ] }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code where the document was issued. Defaults to `ZA` for South Africa.", "pattern": "^[A-Z]{2}$", "default": "ZA" }, "number": { "type": "string", "description": "The document number.", "minLength": 1 } }, "required": [ "type", "number" ] } }, "required": [ "type", "identifyingDocument" ] }, { "type": "object", "description": "A business account holder. Business verification is for South African registered businesses only today; the `country` field is exposed for parity with the upstream `BusinessRegistrationInput` contract.", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "business" ], "description": "The account holder type." }, "registrationNumber": { "type": "string", "description": "The South African business registration number." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code where the business is registered. Defaults to `ZA` for South Africa.", "pattern": "^[A-Z]{2}$", "default": "ZA" }, "name": { "type": "string", "description": "The registered business name.", "maxLength": 60 }, "phone": { "type": "string", "description": "Phone number to verify against the account holder details, if available." }, "email": { "type": "string", "format": "email", "description": "Email address to verify against the account holder details, if available." } }, "required": [ "type", "registrationNumber" ] } ] }, "VerifiedBankAccount": { "type": "object", "description": "The bank account as resolved by the verification provider.", "properties": { "bank": { "type": [ "string", "null" ], "description": "The bank where the account is held. May be `null` if the account is invalid or cannot be verified." }, "branchCode": { "type": [ "string", "null" ], "description": "The branch code of the bank account. May be `null` if the account is invalid or cannot be verified." }, "number": { "type": [ "string", "null" ], "description": "The bank account number that was verified. May be `null` if the account is invalid or cannot be verified." }, "type": { "type": [ "string", "null" ], "description": "The type of bank account. May be `null` if the account is invalid or cannot be verified." } } }, "VerifiedAccountHolder": { "description": "The verified account holder details. Either an individual or a business. Mirrors the request `accountHolder` shape — per-check verdicts live on the `verificationResult.accountHolder` sub-object on the verification resource.", "discriminator": { "propertyName": "type" }, "oneOf": [ { "type": "object", "description": "A verified individual account holder.", "properties": { "type": { "type": "string", "enum": [ "individual" ], "description": "The type of account holder." }, "familyName": { "type": "string", "description": "The family name (surname) of the account holder. Omitted if the caller did not provide a `familyName` in the request and the bank did not return one." }, "initials": { "type": "string", "description": "The initials of the account holder. Omitted if the caller did not provide `initials` in the request and the bank did not return any." }, "identifyingDocument": { "type": "object", "description": "The identifying document details. Omitted when the bank did not return a document.", "properties": { "type": { "type": "string", "description": "The type of identifying document.", "enum": [ "identity_document", "passport" ] }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of the document.\nBank account verification is a South African–only service, so in\npractice this is typically `ZA`. The field reflects whatever the\nupstream verification returned and is not normalized.\n" }, "number": { "type": "string", "description": "The document number." } }, "required": [ "type", "country", "number" ] } }, "required": [ "type" ] }, { "type": "object", "description": "A verified business account holder.", "properties": { "type": { "type": "string", "enum": [ "business" ], "description": "The type of account holder." }, "registrationNumber": { "type": "string", "description": "The registration number of the business. Omitted if the bank did not return one." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code where the business is registered. Echoed from the request when supplied." }, "name": { "type": "string", "description": "The registered name of the business. Omitted if the bank did not return one." } }, "required": [ "type" ] } ] }, "VerificationResult": { "type": "string", "description": "The outcome of a single verification check. `verified` indicates the data matched, `refuted` indicates it did not match, and `indeterminate` indicates the check could not be performed conclusively (e.g. the bank does not support the check, the upstream system is unavailable, or the field was not provided).", "enum": [ "verified", "refuted", "indeterminate" ], "example": "verified" }, "BankAccountVerification": { "type": "object", "description": "A bank account verification resource.", "properties": { "id": { "type": "string", "description": "The unique identifier for this bank account verification. Formatted as `bav_` followed by a 22-character base62 identifier.", "example": "bav_1Q0PsIJvEtkwdCNYMSaVuR" }, "bankAccount": { "$ref": "#/components/schemas/VerifiedBankAccount" }, "accountHolder": { "$ref": "#/components/schemas/VerifiedAccountHolder" }, "verificationResult": { "type": "object", "description": "The verification outcome. The shape mirrors the request: `bankAccount` and `accountHolder` sub-objects carry the per-check verdicts for the corresponding fields in the request. `outcome` is the rolled-up decision.\n\n**Outcome derivation:** `outcome` is `refuted` if any per-field verdict under `bankAccount` or `accountHolder` is `refuted`, OR if the bank tells us the account is closed (`bankAccount.isOpen === false`) — a closed account is treated as not safely usable even when every identity/account-holder check passes. Otherwise `outcome` is `indeterminate` if any verdict is `indeterminate` and none are `refuted`; otherwise `verified`.\n\n**Verdict values:** every verdict is one of `verified`, `refuted`, or `indeterminate` — never `null`. `indeterminate` is used when the bank could not perform the check (or when the caller did not supply the input needed to perform it).\n\n**Bank-returned facts:** `isOpen`, `isOpenForMoreThanThreeMonths`, `acceptsDebits`, and `acceptsCredits` are `boolean | null`. `null` means the bank did not return a value (typical when `outcome` is `indeterminate`). The `outcome` override above only fires on an explicit `false` for `isOpen`, not on `null`.", "properties": { "outcome": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "The rolled-up verification outcome." }, "bankAccount": { "type": "object", "description": "Per-check verdicts and bank-returned facts for the bank account.", "properties": { "exists": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the account exists at the specified bank." }, "typeMatch": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the account type matches. If `type` was not provided in the request, this is `indeterminate`." }, "isOpen": { "type": [ "boolean", "null" ], "description": "Whether the account is currently open. `null` when the bank did not return a value." }, "isOpenForMoreThanThreeMonths": { "type": [ "boolean", "null" ], "description": "Whether the account has been open for more than three months. `null` when the bank did not return a value." }, "acceptsDebits": { "type": [ "boolean", "null" ], "description": "Whether the account accepts debit transactions. `null` when the bank did not return a value." }, "acceptsCredits": { "type": [ "boolean", "null" ], "description": "Whether the account accepts credit transactions. `null` when the bank did not return a value." } }, "required": [ "exists", "typeMatch", "isOpen", "isOpenForMoreThanThreeMonths", "acceptsDebits", "acceptsCredits" ] }, "accountHolder": { "oneOf": [ { "type": "object", "description": "Per-check verdicts for an individual account holder.", "properties": { "identifyingDocument": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the identifying document (identity number or passport number) matches the account holder on record." }, "familyName": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the family name matches the account holder on record." }, "initials": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the initials match the account holder on record." }, "phone": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the phone number matches the account holder details on record. `indeterminate` when `phone` was not provided in the request or when the bank could not perform the check." }, "email": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the email address matches the account holder details on record. `indeterminate` when `email` was not provided in the request or when the bank could not perform the check." } }, "required": [ "identifyingDocument", "familyName", "initials", "phone", "email" ] }, { "type": "object", "description": "Per-check verdicts for a business account holder.", "properties": { "registrationNumber": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the business registration number matches the account holder on record." }, "name": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the registered business name matches the account holder on record." }, "phone": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the phone number matches the account holder details on record. `indeterminate` when `phone` was not provided in the request or when the bank could not perform the check." }, "email": { "allOf": [ { "$ref": "#/components/schemas/VerificationResult" } ], "description": "Whether the email address matches the account holder details on record. `indeterminate` when `email` was not provided in the request or when the bank could not perform the check." } }, "required": [ "registrationNumber", "name", "phone", "email" ] } ] } }, "required": [ "outcome", "bankAccount", "accountHolder" ] }, "createdAt": { "type": "string", "description": "The UTC timestamp indicating when the bank account verification was created. Formatted as an ISO 8601 string (e.g., `2024-01-15T09:30:00Z`).", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The UTC timestamp indicating when the bank account verification was last modified. Bank account verifications are immutable, so this value always matches `createdAt`. Included to align with the standard v2 resource shape.", "format": "date-time" } }, "required": [ "id", "bankAccount", "accountHolder", "verificationResult", "createdAt", "updatedAt" ] }, "DisputeEvidenceFile": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "caseReference", "evidenceType", "filename", "contentType", "size", "createdAt" ], "properties": { "id": { "type": "string", "example": "file_2xKq9mNpLr8ZtWvYbCdEfG" }, "type": { "type": "string", "const": "dispute_evidence" }, "caseReference": { "type": "string", "minLength": 1, "maxLength": 255, "example": "AMZ-2026-001" }, "evidenceType": { "type": "string", "const": "consolidated" }, "filename": { "type": "string", "example": "evidence.pdf" }, "contentType": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "minimum": 1, "maximum": 52428800, "example": 184231 }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-07-13T12:00:00.000Z" } } }, "ErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "code", "title", "detail" ], "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" } } }, "ForbiddenErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "code", "title", "detail", "missingScopes" ], "properties": { "code": { "type": "string", "const": "FORBIDDEN" }, "title": { "type": "string" }, "detail": { "type": "string" }, "missingScopes": { "type": "array", "description": "OAuth scopes required by the endpoint but absent from the token.", "items": { "type": "string" } } } }, "FingerprintMetadata": { "type": "object", "description": "Flat key-value object stored with the fingerprint event. Nested objects and arrays are rejected. Serialized JSON must be at most 4096 UTF-8 bytes.", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "FingerprintSignals": { "type": "object", "additionalProperties": false, "properties": { "platform": { "type": "string", "enum": [ "web", "ios", "android" ] }, "ip": { "type": "object", "additionalProperties": false, "properties": { "address": { "type": "string" }, "country": { "type": "string" } } }, "device": { "type": "object", "additionalProperties": false, "properties": { "os": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "version": { "type": "string" } } }, "browser": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "version": { "type": "string" } } }, "userAgent": { "type": "string" }, "screenResolution": { "type": "object", "additionalProperties": false, "required": [ "width", "height" ], "properties": { "width": { "type": "number" }, "height": { "type": "number" } } }, "timezone": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } } } } } }, "FingerprintEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "correlationId", "deviceId", "signals", "createdAt" ], "properties": { "id": { "type": "string", "description": "Stitch event resource id." }, "correlationId": { "type": "string", "maxLength": 128, "description": "Merchant business reference for this submit." }, "userId": { "type": "string", "description": "Merchant-supplied user identifier." }, "deviceId": { "type": "string", "description": "Client-scoped device identifier." }, "metadata": { "$ref": "#/components/schemas/FingerprintMetadata" }, "signals": { "$ref": "#/components/schemas/FingerprintSignals" }, "createdAt": { "type": "string", "format": "date-time" } } }, "FingerprintDevice": { "type": "object", "additionalProperties": false, "required": [ "id", "lastSeenAt" ], "properties": { "id": { "type": "string", "description": "Public device id (same value as deviceId on events)." }, "lastSeenAt": { "type": "string", "format": "date-time" }, "signals": { "$ref": "#/components/schemas/FingerprintSignals" } } }, "DisputeEvidenceSubmission": { "description": "Successful evidence submission receipt. `status` discriminates the wire shape. `received` is the current Chargeback-Dash receipt. `pending` is the webhook-aligned body that repeats `transactions[]` and nests the submission under `evidenceSubmission`.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "caseReference", "status", "submittedAt", "files" ], "properties": { "caseReference": { "type": "string", "minLength": 1, "maxLength": 255, "example": "AMZ-2026-001" }, "status": { "type": "string", "const": "received" }, "submittedAt": { "type": "string", "format": "date-time", "example": "2026-07-13T12:05:00.000Z" }, "submittedBy": { "type": "string", "minLength": 1, "maxLength": 255, "example": "disputes@amazon.com" }, "comments": { "type": "string", "minLength": 1, "maxLength": 5000, "example": "All requested documentation attached." }, "files": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "fileId", "filename", "evidenceType" ], "properties": { "fileId": { "type": "string", "example": "file_2xKq9mNpLr8ZtWvYbCdEfG" }, "filename": { "type": "string", "example": "evidence.pdf" }, "evidenceType": { "type": "string", "const": "consolidated" } } } } } }, { "type": "object", "additionalProperties": false, "required": [ "caseReference", "status", "evidenceDueAt", "transactions", "evidenceSubmission" ], "properties": { "caseReference": { "type": "string", "minLength": 1, "maxLength": 255, "example": "AMZ-2026-001" }, "status": { "type": "string", "const": "pending", "description": "Case status. Matches `dispute.evidence_received`." }, "evidenceDueAt": { "type": "string", "format": "date-time", "example": "2026-07-20T21:59:59.999Z" }, "transactions": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "createdAt", "amount", "scheme", "acquirer", "reasonCode", "reasonDescription", "authorizationCode", "retrievalReferenceNumber", "acquirerReferenceNumber", "externalReference", "eci", "secure3dVersion", "liabilityShift", "secure3dDecision", "secure3dDecisionReason" ], "properties": { "id": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "amount": { "type": "object", "additionalProperties": false, "required": [ "currency", "amount" ], "properties": { "currency": { "type": "string", "example": "ZAR" }, "amount": { "type": "number", "example": 1500 } } }, "scheme": { "type": [ "string", "null" ] }, "acquirer": { "type": "string" }, "reasonCode": { "type": "string" }, "reasonDescription": { "type": [ "string", "null" ] }, "authorizationCode": { "type": "string" }, "retrievalReferenceNumber": { "type": "string" }, "acquirerReferenceNumber": { "type": "string" }, "externalReference": { "type": [ "string", "null" ] }, "eci": { "type": [ "string", "null" ] }, "secure3dVersion": { "type": [ "string", "null" ] }, "liabilityShift": { "type": "string" }, "secure3dDecision": { "type": [ "string", "null" ] }, "secure3dDecisionReason": { "type": [ "string", "null" ] } } } }, "evidenceSubmission": { "type": "object", "additionalProperties": false, "required": [ "submittedAt", "submittedBy", "files" ], "properties": { "submittedAt": { "type": "string", "format": "date-time", "example": "2026-07-13T12:05:00.000Z" }, "submittedBy": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255, "example": "disputes@amazon.com" }, "comments": { "type": "string", "minLength": 1, "maxLength": 5000, "example": "All requested documentation attached." }, "files": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "fileId", "filename", "evidenceType" ], "properties": { "fileId": { "type": "string", "example": "file_2xKq9mNpLr8ZtWvYbCdEfG" }, "filename": { "type": "string", "example": "evidence.pdf" }, "evidenceType": { "type": "string", "example": "consolidated" } } } } } } } } ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this webhook event." }, "type": { "type": "string", "description": "The type of webhook event." }, "data": { "type": "object", "description": "The data for this webhook event." }, "createdAt": { "type": "string", "description": "The UTC timestamp indicating when the webhook event was created. Formatted as an ISO 8601 string (e.g., 2024-01-15T09:30:00Z)." } } } }, "examples": { "PendingTerminalSession": { "summary": "Pending terminal session", "description": "This example shows a terminal session that is still pending completion on the terminal device.", "value": { "id": "ts_i0sspe2eZvKYDS2Cd31jOCgZ", "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "source": "api", "intent": { "charge": { "amount": 350.5, "currency": "ZAR" } }, "customer": { "name": "John Doe", "email": "john.doe@example.com", "phone": "+27612345678", "externalReference": "CUSTOMER#7652394832" }, "status": "pending", "nonce": "9599a853-4333-4359-89de-658bfc86773a", "metadata": { "example": "metadata" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" } }, "SuccessfulTerminalSession": { "summary": "Successful terminal session", "description": "This example shows a terminal session that completed successfully.", "value": { "id": "ts_i0sspe2eZvKYDS2Cd31jOCgZ", "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "source": "api", "intent": { "charge": { "amount": 350.5, "currency": "ZAR" } }, "customer": { "name": "John Doe", "email": "john.doe@example.com", "phone": "+27612345678", "externalReference": "CUSTOMER#7652394832" }, "status": "success", "outcome": { "charge": { "id": "89587578-9aad-4058-8f3c-b5c19d5e3ac5", "type": "in_person_card", "card": { "bin": "42424242", "last4": "4242", "expiry": { "month": "12", "year": "29" }, "network": "visa", "fundingType": "debit", "issuer": { "name": "standard bank", "country": "ZA" } }, "retrievalReferenceNumber": "1234567890", "networkTransactionIdentifier": "1234567890", "amount": 350.5, "currency": "ZAR", "status": "success", "metadata": { "example": "metadata" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" } }, "nonce": "9599a853-4333-4359-89de-658bfc86773a", "metadata": { "example": "metadata" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" } }, "FailedTerminalSession": { "summary": "Failed terminal session", "description": "This example shows a terminal session that failed.", "value": { "id": "ts_i0sspe2eZvKYDS2Cd31jOCgZ", "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "source": "api", "intent": { "charge": { "amount": 350.5, "currency": "ZAR" } }, "customer": { "name": "John Doe", "email": "john.doe@example.com", "phone": "+27612345678", "externalReference": "CUSTOMER#7652394832" }, "status": "failure", "failureReason": "cancelled_by_api", "nonce": "9599a853-4333-4359-89de-658bfc86773a", "metadata": { "example": "metadata" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" } }, "SuccessfulRefund": { "summary": "Successful refund", "description": "This example shows a refund that completed successfully.", "value": { "id": "refund_1234567890", "type": "card", "charge": "charge_1Q0PsIJvEtkwdCNYMSaVuRz6", "amount": 30, "currency": "ZAR", "reason": "requested_by_customer", "status": "success", "nonce": "9599a853-4333-4359-89de-658bfc86773a", "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" } }, "FailedRefund": { "summary": "Failed refund", "description": "This example shows a refund that failed with an authorization error.", "value": { "id": "refund_1234567890", "charge": "charge_1Q0PsIJvEtkwdCNYMSaVuRz6", "amount": 30, "currency": "ZAR", "reason": "requested_by_customer", "status": "failure", "nonce": "9599a853-4333-4359-89de-658bfc86773a", "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" } }, "TerminalSessionSuccessWebhookEvent": { "summary": "Terminal session success webhook event", "description": "This example shows a terminal session success webhook payload.", "value": { "id": "wev_1o1jU6Y8whOrGcmXzfeDq3wQ", "type": "terminal-session.success", "data": { "id": "ts_i0sspe2eZvKYDS2Cd31jOCgZ", "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "source": "api", "intent": { "charge": { "amount": 350.5, "currency": "ZAR" } }, "customer": { "name": "John Doe", "email": "john.doe@example.com", "phone": "+27612345678", "externalReference": "CUSTOMER#7652394832" }, "status": "success", "outcome": { "charge": { "id": "89587578-9aad-4058-8f3c-b5c19d5e3ac5", "type": "in_person_card", "card": { "bin": "42424242", "last4": "4242", "expiry": { "month": "12", "year": "29" }, "network": "visa", "fundingType": "debit", "issuer": { "name": "standard bank", "country": "ZA" } }, "retrievalReferenceNumber": "1234567890", "networkTransactionIdentifier": "1234567890", "amount": 350.5, "currency": "ZAR", "status": "success", "metadata": { "example": "metadata" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" } }, "nonce": "9599a853-4333-4359-89de-658bfc86773a", "metadata": { "example": "metadata" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" }, "createdAt": "2024-01-15T09:36:00Z" } }, "TerminalSessionDisbursementSuccessWebhookEvent": { "summary": "Terminal session disbursement success webhook event", "description": "This example shows a disbursement terminal session success webhook payload.", "value": { "id": "wev_2p3qT5rN1sGhKL8mBe9fJdCv", "type": "terminal-session.success", "data": { "id": "ts_k3mRvN8pLqWxYZ5Af72jTBcE", "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "source": "api", "intent": { "disbursement": { "amount": 150, "currency": "ZAR" } }, "status": "success", "outcome": { "disbursement": { "id": "3f8c2a1b-7e9d-4f5a-b6c0-8d2e4f6a0b1c", "type": "in_person_card", "card": { "bin": "42424242", "last4": "4242", "expiry": { "month": "12", "year": "29" }, "network": "visa", "fundingType": "debit", "issuer": { "name": "standard bank", "country": "ZA" } }, "retrievalReferenceNumber": "9876543210", "networkTransactionIdentifier": "9876543210", "amount": 150, "currency": "ZAR", "status": "success", "metadata": {}, "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:05:00Z" } }, "nonce": "b7e3f1a2-9c84-4d5e-a6b0-8f2d4e6c0a1b", "metadata": {}, "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:05:00Z" }, "createdAt": "2024-01-15T10:06:00Z" } }, "TerminalSessionRefundSuccessWebhookEvent": { "summary": "Terminal session refund success webhook event", "description": "This example shows a refund terminal session success webhook payload.", "value": { "id": "wev_4r5sT6uV7wXyZ8aBc9dEfGh", "type": "terminal-session.success", "data": { "id": "ts_n4pQrS7tUvWxYz8AbCdEfGh", "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "intent": { "refund": { "terminalSession": "ts_i0sspe2eZvKYDS2Cd31jOCgZ", "amount": 45, "currency": "ZAR", "reason": "requested_by_customer" } }, "status": "success", "outcome": { "refund": { "id": "9a8b7c6d-5e4f-4321-a987-6543210fedcb", "type": "in_person_card", "charge": "89587578-9aad-4058-8f3c-b5c19d5e3ac5", "amount": 45, "currency": "ZAR", "reason": "requested_by_customer", "status": "success", "nonce": "refund-reference-123", "metadata": {}, "createdAt": "2024-01-15T11:00:00Z", "updatedAt": "2024-01-15T11:00:00Z" } }, "nonce": "refund-reference-123", "metadata": {}, "createdAt": "2024-01-15T11:00:00Z", "updatedAt": "2024-01-15T11:00:00Z" }, "createdAt": "2024-01-15T11:01:00Z" } }, "TerminalSessionFailureWebhookEvent": { "summary": "Terminal session failure webhook event", "description": "This example shows a terminal session failure webhook payload.", "value": { "id": "wev_3p9xA2mQ6LfHjR3kUb1tW7nP", "type": "terminal-session.failure", "data": { "id": "ts_i0sspe2eZvKYDS2Cd31jOCgZ", "terminal": "dGVybWluYWwvMmNiN2NhMTQtNGQwYi00ODg3LTk2MWItOTRmYWYzMzJkMGYw", "source": "api", "intent": { "charge": { "amount": 350.5, "currency": "ZAR" } }, "customer": { "name": "John Doe", "email": "john.doe@example.com", "phone": "+27612345678", "externalReference": "CUSTOMER#7652394832" }, "status": "failure", "failureReason": "expired", "nonce": "9599a853-4333-4359-89de-658bfc86773a", "metadata": { "example": "metadata" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:35:00Z" }, "createdAt": "2024-01-15T09:36:00Z" } } } } }