--- title: "Reverse (close) a payin by payin token" method: POST path: "/payin/{user_token}/{payin_token}/reverse" tags: ["Payin"] --- # Reverse (close) a payin by payin token `POST /payin/{user_token}/{payin_token}/reverse` ## Request - Base URL: `https://api.masspay.io/v1.0.0` - URL: `https://api.masspay.io/v1.0.0/payin/{user_token}/{payin_token}/reverse` - Auth: one of: - API key in header `Authorization` - API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) This **POST** endpoint reverses, or closes, a pay-in transaction for the user and payin token provided.
Both the effect and the conditions depend on how the pay-in was funded: A pay-in that has already been reversed, or that is in a non-reversible state for its funding type, returns a `400`.
On success the pay-in transitions to `CANCELLED` and the updated pay-in object is returned. ## Headers - `Idempotency-Key` string ## Request body - ReversePayinReq: Optional details for a pay-in reversal. - `reason` string: Optional free-text reason for the reversal, stored for audit purposes ## Response `200` OK - InitiatePayinResp: Response returned when initiating a pay-in transaction. - `payin_token` string, nullable: Token representing the initiated pay-in transaction. Use this for subsequent commit/status calls. - `funding_code` string, nullable: Funding code for tracking the payment source (e.g. cash deposit reference shown to the user). - `client_transfer_id` string: A client defined transfer identifier. This is the unique ID assigned to the transfer on your system. Max 50 characters. A value another payout of yours already carries is rejected with `400 Bad request` and `Duplicate client id. Existing payout token: payout_` in `error.details`. By default a value becomes reusable once the earlier payout is `ERROR` or `EXPIRED` (or is a `PENDING` quote past its expiration); any other status, including `CANCELLED`, keeps it reserved. Accounts configured for strict uniqueness never allow reuse, whatever the earlier payout's status. - `destination_token` string: Token representing the destination wallet/account where funds will be deposited. - `payment_reference` string, nullable: Payment reference identifier from the partner/network. - `required_action` 'CASH_DEPOSIT_AT_STORE' | 'TRANSFER' | 'BANK_AUTHORIZATION' | 'CARD_CAPTURE' | 'NONE': Additional action required from the user/system to complete the pay-in. NONE means no further action is needed. - `instructions` string: Human-readable instructions for completing the required action. - `status` 'INITIATED' | 'PROCESSING' | 'COMPLETED' | 'ERROR' | 'CANCELLED': Current status of the pay-in. INITIATED = created and awaiting action; PROCESSING = in flight at partner; COMPLETED = funds settled; ERROR = failed. - `requires_commit` boolean: Whether a separate commit call is required to finalize the transaction. - `source_amount` number, double, nullable: Amount in source currency. - `destination_amount` number, double, nullable: Amount in destination currency (after FX, if applicable). - `exchange_rate` number, double, nullable: Exchange rate applied between source and destination currencies. - `fee` number, double, nullable: Fee charged for the pay-in, in source currency. - `source_currency_code` string, nullable: Source currency code (ISO 4217, or asset code for crypto). - `destination_currency_code` string, nullable: Destination currency code (ISO 4217, or asset code for crypto). - `network_response` NetworkResponse: Network-level response details from the underlying card/network partner. Fields populated vary by partner and by which value-added checks were requested. - `action_code` string: Network action/response code. '00' indicates approval; non-zero values indicate decline or error reasons. - `approval_code` string, nullable: Authorization/approval code returned by the network on a successful authorization. - `address_verification` string, nullable: AVS result code returned when AVS was set to RUN or RUN_AND_VALIDATE. Typical values include Y (full match), A (address only), Z (postal only), N (no match), U (unavailable). - `cvv2_result_code` string, nullable: CVV2 result code returned when a CVV was supplied. Typical values: M (match), N (no match), P (not processed), U (unavailable), S (should be present). - `cavv_result_code` string, nullable: CAVV verification result code returned by the network when 3DS authentication data was supplied. - `ani_result` 'MATCH' | 'PARTIAL_MATCH' | 'NO_MATCH' | 'NOT_CHECKED' | 'UNAVAILABLE', nullable: Outcome of the Account Name Information match, populated when ANI was set to RUN or RUN_AND_VALIDATE. Absent when ANI was skipped. - `account_number` string, nullable: Account number of the bank account created for this transaction. - `routing_number` string, nullable: Bank routing number (ABA) of the account created for this transaction. - `swift_bic` string, nullable: Bank swift BIC code of the account created for this transaction. - `bank_name` string, nullable: Bank name of the account created for this transaction. - `bank_address` string, nullable: Bank address of the account created for this transaction. - `name_on_account` string, nullable: Name on the bank account created for this transaction. - `network_id` string, nullable: Identifier of the card network/partner that processed the transaction. - `response_reason_code` string, nullable: Network reason code providing additional detail about the response. - `exemption_reason_code` string, nullable: Code indicating any SCA (Strong Customer Authentication) exemption applied to the transaction. - `deposits` PayinDeposit[]: Deposits made toward this pay-in. A pay-in may be funded by multiple deposits. - `token` string: Token representing the deposit. - `external_id` string, nullable: External identifier of the deposit at the partner/network. - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED' | 'RETURNED': Current status of the deposit. PENDING = deposit expected but not yet received; PROCESSING = deposit received and being processed; COMPLETED = deposit settled; FAILED = deposit failed; EXPIRED = deposit window elapsed without receiving funds; RETURNED = settled deposit returned to the sender through the originating network. ACH and wire deposits auto-fund on receipt and move directly to COMPLETED. - `deposit_amount` number, double, nullable: Amount deposited, in the deposit currency. - `deposit_currency` string, nullable: Currency/asset code of the deposit (ISO 4217, or asset code for crypto). - `fiat_amount` number, double, nullable: Equivalent fiat amount of the deposit. - `fiat_currency` string, nullable: Fiat currency code of the equivalent amount (ISO 4217). - `fee` string: Fee that was applied to the deposit in fiat currency - `transaction_reference` string, nullable: Reference for the deposit transaction (e.g. blockchain tx hash or bank reference). - `metadata` object, nullable: Details MassPay captured about how the deposit arrived. `method` says which rail delivered it; the other fields are present only when the rail supplied them. For bank deposits (`ach`, `wire`, `rtp`) the sender's account, routing number and name are included. For a `wire` deposit the reference messages carried on the Fedwire are included as well, so the deposit can be reconciled against an invoice or order: the IMAD/OMAD identifiers, the sender's and the beneficiary's reference, the payment purpose, and the originator-to-beneficiary information lines in the order they were sent. - `method` string: Rail the deposit arrived on, e.g. `ach`, `wire` or `rtp`. - `account` string: Sender's account number as reported by the network. - `routing` string: Sender's bank routing number. - `name` string: Sender's name as reported by the network. - `imad` string: Fedwire Input Message Accountability Data of the wire. Wire deposits only. - `omad` string: Fedwire Output Message Accountability Data of the wire. Wire deposits only. - `sender_reference` string: Reference assigned by the sending bank. Wire deposits only. - `beneficiary_reference` string: Reference the sender addressed to the beneficiary. Wire deposits only. - `purpose` string: Payment purpose stated on the wire, when the sender provided one. Wire deposits only. - `originator_to_beneficiary` string[]: Originator-to-beneficiary information lines, in the order they appeared on the wire; empty lines are omitted. Wire deposits only. - `return_reason_code` string, nullable: Normalized reason the deposit was returned (see `DepositReturnReason` for values). Null unless the deposit status is RETURNED. - `network_return_code` string, nullable: Network-specific return code transmitted on the rail the deposit was received on (e.g. ACH `R23`, wire `CUST`), translated from `return_reason_code`. Null unless the deposit status is RETURNED. - `return_reason` string, nullable: Free-text reason supplied when the deposit was returned. Null unless the deposit status is RETURNED. - `return_fee` number, nullable: Fee charged for returning the deposit; see `fee_payer` for whether it was debited from the destination wallet or withheld from the returned funds. Null unless the deposit status is RETURNED. - `fee_payer` 'CLIENT' | 'DEPOSITOR', nullable: Who absorbed the return fee. `CLIENT`: the wallet was debited `fiat_amount` plus the fee and the sender received the full deposit. `DEPOSITOR` (wire deposits only): the fee was withheld from the returned funds. Null unless the deposit status is RETURNED. - `returned_at` string, date-time, nullable: Timestamp when the deposit was returned. - `created_at` string, date-time: Timestamp when the deposit was created. - `completed_at` string, date-time, nullable: Timestamp when the deposit was completed. - `updated_at` string, date-time, nullable: Timestamp when the deposit was last updated. - `error` string, nullable: Error message when the pay-in fails. Format for partner failures: ' [] '. - `error_type` 'VALIDATION' | 'PARTNER' | 'GENERIC', nullable: Category of the error. VALIDATION = client request issue; PARTNER = upstream partner/network failure; GENERIC = unclassified. - `source_token` string: Token that represent the rail through which the pay-in will be collected from. I.e. Crypto Deposit, Cash Deposit, Bank Debit, etc. List of available service can be obtained through the catalog pay-ins endpoint ## Other responses - `400`: Bad request. The pay-in cannot be reversed in its current state — for example a card authorization that has already been captured, or a pay-in that has already been reversed. - `401`: Unauthorized. - `403`: Forbidden. - `404`: Not found. - `405`: Method Not Allowed. - `500`: Internal server error. - `504`: Gateway Time-out. ## Changes - **2026-11-03** `f9fa41b7c45c`: 1 info - endpoint added [Operation history](https://skmtc.dev/masspay/apis/masspay-api/changes/payin/:user_token/:payin_token/reverse/post.md) --- [API](https://skmtc.dev/masspay/apis/masspay-api.md) - [All operations](https://skmtc.dev/masspay/apis/masspay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/masspay/apis/masspay-api/revisions/f9fa41b7c45c?raw)