Introduction
From Form3 API Docs
Both inbound and outbound recalls are represented in the Form3 API by the Payment Recall resource, which is a child resource of the Payment resource the recall is for. The Recall Submission or Recall Admission resources are children of the Recall resource and indicate if a recall is inbound (Admission) or outbound (Submission).
Fetch Recall Decision
Get a single Recall Decision resource.
HTTP Request
v1/transaction/payments/{payment_id}/recalls/{recall_id}/decisions/{decision_id}
URL Parameters
decision_id
REQUIRED — string, unique identifier (UUID)
ID of the Payment Recall Decision resource to fetch.
payment_id
REQUIRED — string, unique identifier (UUID)
ID of the Payment resource that is being recalled.
recall_id
REQUIRED — string, unique identifier (UUID)
ID of the Payment Recall resource that is admitted.
Response Attributes
answer
ALWAYS — string, enum
Answer to the recall request.
Values
accepted
Recall has been accepted. If partially accepted then `recall_amount.amount` will advise what amount will be returned.
pending
Recall is still pending. Used in FedNow only.
rejected
Recall has been rejected.
agents
SOMETIMES — object
Information around the Agent who has taken charges in relation to the recall.
Children
.identification
SOMETIMES — object
Information about the financial institution.
.bank_id
SOMETIMES — string
Identification code of the financial institution.
bank_id_code
SOMETIMES — string
The type of identification provided in 'bank_id'. Always 'USABA'.
.role
SOMETIMES — string, enum
Role of the agent in the payment chain. Enum of pre-defined values, new values can be added when needed, e.g. 'InstructingAgent'.
ChargesAgent
Agent that takes the transaction charges or to which the transaction charges are due.
charges_amount
SOMETIMES — object
Information about the charges.
Children
.amount
SOMETIMES — string
Amount of charges to be taken for the recall and not returned to the recall originator.
.currency
SOMETIMES — string
ISO currency code for the charges amount. Must be `USD`.
reason
SOMETIMES — string
Further explanation of the reason given in reason_code. Only supported for certain reason codes, see the value descriptions in reason_code for which codes require a reason. Max 105 characters.
reason_code
SOMETIMES — string, enum
Reason for a rejected decision. Populated when answer is rejected, otherwise ignored. Must be a 4-character code allowed from the ISO 20022 externalized PaymentCancellationRejection1Code list.
recall_amount
SOMETIMES — object
Amount to be returned if the recall is partially accepted by the counterparty.
Children
.amount
SOMETIMES — string [0-9]{0,9}.[0-9]{2}
Amount that is being returned when the response to the recall is partially returned.
.currency
SOMETIMES — string
[ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) for the recall amount. Must be `USD`.
resolution_related_information
SOMETIMES — object
Information about the return transaction that is returning the payment.
Children
.clearing_channel
SOMETIMES — string, enum
Clearing channel of the return payment, if being returned outside of original payment scheme, i.e. RTP or FedNow.
MPNS
MassPaymentNetSystem - ACH Payment.
RTGS
RealTimeGrossSettlementSystem - Fedwire Payment.
RTNS
RealTimeNetSettlementSystem - CHIPS Payment.
.references
SOMETIMES — array of object
Array that can contain up to 5 references related to the return payment.
.type
SOMETIMES — string, enum
Type of reference that the value relates to.
EndToEndId
End-to-End ID of the return payment as assigned by the initiating party. Only applicable to FedNow.
TxId
Transaction ID of the return payment as assigned by the first instructing agent. Only applicable to FedNow. Either Transaction ID or UETR must be present, but not both.
UETR
UETR of the original transaction for RTP. UETR of the Return transaction for FedNow.
UniqueSchemeId
Unique identifier of the return payment processed outside of RTP, e.g. Trace Number for ACH, IMAD for Fedwire or SSN for CHIPS. Only applies to Recall Decisions for RTP where Return is being processed outside of RTP.
.value
Value of the reference for the selected type.
.settlement_date
SOMETIMES — string, date YYYY-MM-DD
The settlement date of the return payment processed.
Response Relationships
decision_admission
ALWAYS — object
Information about the Recall Decision Admission resource.
Children
.data
ALWAYS — object, API resource
JSON:API wrapper structure, contains information about the Recall Decision Admission.
.id
ALWAYS — string, unique identifier (UUID)
ID of the Recall Decision Admission resource.
.type
ALWAYS — string
The type of resource, always 'recall_decision_admissions'.
decision_submission
ALWAYS — object
Information about the Recall Decision Submission resource.
Children
.data
ALWAYS — object, API resource
JSON:API wrapper structure, contains information about the Recall Decision Submission.
.id
ALWAYS — string, unique identifier (UUID)
ID of the Recall Decision Submission resource.
.type
ALWAYS — string
The type of resource, always 'recall_decision_submissions'.
payment
ALWAYS — object
Information about the original Payment Recall resource that is being recalled.
Children
.data
ALWAYS — object, API resource
JSON:API wrapper structure, contains information about the Recalled Payment.
.id
ALWAYS — string, unique identifier (UUID)
ID of the Payment Recall resource that is being recalled.
.type
ALWAYS — string
The type of resource, always 'payments'.
recall
ALWAYS — object
Information about the Recall resource.
Children
.data
ALWAYS — object, API resource
JSON:API wrapper structure, contains information about the Payment Recall.
.id
ALWAYS — string, unique identifier (UUID)
ID of the Recall resource.
.type
ALWAYS — string
The type of resource, always 'recalls'.
Example - Fetch a Payment Recall Decision
GET v1/transaction/payments/c419bbef-f586-48b1-bbbd-7ef4aef21ec2/recalls/a74b9b67-fa61-4013-ab0e-a252963d4151/decisions/c15ee5ce-2d78-42e1-a03f-26805f526f8d
Accept: application/json
Host: api.form3.tech
Date: Mon, 10 June 2024 20:04:24 GMT
Authorization: Signature keyId="49a7aac7-3cd0-4eca-9697-b195fc2a898a",algorithm="rsa-sha256", headers="(request-target) accept host date", signature="dGVzdHNldHNldHNldHNldHNhZGFkYXNkIGkgdGFraWUgdGFt"
Example - Response
{
"data": {
"id": "9513e122-d8db-4947-92e0-4c3f4010afa7",
"type": "recall_decisions",
"organisation_id": "8cfe9afd-86c1-4caa-b7b8-c00fc43aeb6b",
"attributes": {
"answer": "rejected",
"recall_amount": {
"currency": "USD",
"amount": "24.00"
},
"reason_code": "NARR",
"reason": "Narrative reason provided here"
},
"relationships": {
"payment": {
"data": [
{
"type": "payments",
"id": "c419bbef-f586-48b1-bbbd-7ef4aef21ec2"
}
]
},
"recall": {
"data": [
{
"type": "recalls",
"id": "a74b9b67-fa61-4013-ab0e-a252963d4151"
}
]
},
"decision_submission": {
"data": [
{
"type": "recall_decision_submissions",
"id": "786942cd-e886-47b3-be30-a336e1aaa2ba"
}
]
},
"decision_admission": {
"data": [
{
"type": "recall_decision_admissions",
"id": "4c98e12c-c9df-48a6-9f06-5cadf8458b1c"
}
]
}
}
}
}