Request for payment

A request for payment (pain.013) asks a payer to send an instant payment. The bank's customer can send one to a payer at another institution, and can receive one and pay or decline it. Both rails carry it.

Send a request

POST /transfers/realtime/requests asks a payer to pay the account in account_id. It requires an Idempotency-Key.

railstringRequired

fednow or rtp.

account_idstringRequired

The account to be paid. It must be open.

amountintegerRequired

Minor units.

currency_codestringRequired

USD.

debtorobjectRequired

The payer: routing_number, account_number, name and account_type.

requested_execution_datedateOptional

Defaults to the rail's current cycle date.

expires_atdate-timeOptional

Defaults to 23:59:59 ET on the execution date.

remittancestringOptional

What the request is for.

document_numberstringOptional

The invoice or document it refers to.

The result is a Payment Request with direction outbound; its counterparty is the payer. If the service cannot be reached the call answers payments.rail_unavailable. The request is kept, and a scheduler routine sends it again until the service acknowledges it.

How it is answered

Status	Meaning
`sent`	Recorded and sent.
`acknowledged`	The service acknowledged the message.
`received`	The payer's institution answered pain.014 `RCVD`. On a request the bank's customer received: recorded, and the bank answered `RCVD`.
`presented`	pain.014 `PRES`: the payer has seen it.
`accepted`	pain.014 `ACTC`: the payer agreed. The payment has not settled yet.
`paid`	The credit transfer settled. `payment_id` names the Realtime Transfer.
`rejected`	pain.014 `RJCT`, with `reason_code` and `reason`.
`expired`	`expires_at` passed while the request was open.
`cancelled`	Cancelled with a camt.055 before it was paid.
`failed`	The service rejected the message.

A request is open while it is sent, acknowledged, received, presented or accepted. The payer's credit transfer carries the request's id as its end-to-end id. When it arrives for the same account, the bank credits the account and marks the request paid.

When the bank's customer is asked

An incoming pain.013 is recorded with direction inbound against the payer's account and answered RCVD. One for an account number the bank does not have is stored rejected with AC03 and answered RJCT. Then:

POST /payment-requests/{id}/present tells the requester the customer has seen it.
POST /payment-requests/{id}/pay, with an Idempotency-Key, answers ACTC and sends the credit transfer with the request's id as its request_id. That payment passes the same checks as any instant payment, and the request is paid once it is accepted. A request past its expires_at becomes expired instead.
POST /payment-requests/{id}/decline answers RJCT with a reason_code: AC04, AC06, AG01, AM04, CUST, DUPL, FRAD, NARR or RR04.

A request that is not open answers payments.request_not_open.

Cancel and expire

POST /payment-requests/{id}/cancel sends a camt.055 about an open request the bank sent, with operator and a reason_code: DUPL, FRAD, TECH, UPAY, CUST, AGNT, AM09, CURR or CUTA. cancellation_status is requested until the camt.029 answers. CNCL sets the request cancelled. RJCR sets cancellation_status to refused and leaves the request as it was.

In the other direction, a camt.055 about a request the bank's customer received cancels it while it is open, and is refused with ARDT once it is not. A scheduler routine closes open requests whose expires_at has passed through POST /payment-requests/expirations.

Events and testing

Each status is an event type, such as payments.payment_request.paid, with the Payment Request as its data. GET /payment-requests lists requests by account_id, direction, status or rail.

In the sandbox, POST /simulate/transfers/realtime/request plays another institution's customer asking one of the bank's account numbers to pay, and POST /simulate/transfers/realtime/request-cancellation plays the requester cancelling. For a request the bank sends, the simulated payer answers RCVD and ACTC and pays at once. A debtor account number ending in 0000 is rejected with AC04. One ending in 1111 is received and never answered, which leaves the request open to cancel or expire.