A remittance transaction is a resource to transfer payments for a recipient `GET users/wallets/payouts/remittances/recipients/{id}` that is based on a quote `POST /users/wallets/payouts/remittances/quotes`. A recipient can be a person or a business entity.
Request made here are processed asynchronously. Please call the poll resource to know status of request, refer to `GET /users/wallets/payouts/remittances/transactions/{transaction_reference}/statuses'`.
Clients can also subscribe to webhooks `PAYOUT.TRANSACTION.CROSSBORDER.STATUS` and `PAYOUT.TRANSACTION.CROSSBORDER.REVIEW.STATUS` to receive status updates. Please coordinate with the site admin to configure your callback preferences.
### Handling updates in the recipient form before transaction initiation
The fields in recipient form are dynamic in nature and may change due to administrative decisions and regulatory updates.The changes can be due to any one or more of the following:
- Changes to specifications of required or mandatory fields.
- Introduction of new required fields.
- Modifications of allowed values(ENUMS) in the required fields that is different from the value selected by the user previously.
In order to accommodate dynamic nature of recipient form, Matchmove advises the client as below.
- Before initiating remittance transaction, Client should fetch recipient detail using `GET 'users/wallets/payouts/remittances/recipients/{id}'`.
- If there is an update on recipient form, The recipient's status will be in 'UPDATE_REQUIRED'. In such cases, client shall prompt the user to update the details as per the latest recipient form `GET 'users/wallets/payouts/remittances/recipients/forms'`.
- Since modification feature for recipient is not available, client is required to delete the recipient and create a new recipient as per latest recipent form before initiating remittance transaction.
Also, the recipient data such as “Purpose of Payment” is transaction specific and needs to be displayed to the user to allow for modification as applicable for every transaction.
<!-- theme: info -->
> #### Note
> - Funds must be available when initiating a transaction in order to proceed.
> - Please ensure the API integration can handle changes as per latest recipient form.
Header Parameters
X-Auth-User-IDstring Required
MatchMove provided ID for the user.
Authorizationstring
Body Parameters
quote_idstring Required
Represents unique quote id. This should be used to initiate transaction.
recipient_idstring
This represents the unique id of recipient. This id will be used to identify recipient while initiating remittance.
For a transaction, either recipient id or recipient details should be passed.
when a recipient details are passed, then app will try to create a new recipient and use same for transaction.
purpose_of_paymentstring,null
Represents the field where we can pass allowed values for transaction. This field would be similar to purpose of payment for a recipient object.
Values passed here will be used for transaction only. it wont be updated to recipient used in transaction.
user_recipient_relationshipstring,null
Represents the recipient to user relationship. This would be similar to user to recipient relationship captured as part of recipient object.
This would be used for transaction only. It would not be upated back to recipient.
user_occupationstring,null
Represents the employment nature of user. This field is used for transaction only. Any new value used here wont be updated back at user.
user_source_of_incomestring,null
Represents the source of funds for a transaction. This field is used for transaction only. Any new value used here wont be updated back at user.
recipient_detailsobject
This represents the object with which we can create recipient while initiating transaction.
we need to either pass recipient_id or use ths object.
Types of documents to be uploaded when document is required
Enum values:
INVOICE
Show child attributes
messagestring
Displays the message of a transaction.
Default value
Request Received, Processing Started
sourcestring
Contains service provider validation source after submission in JSON. This field can be empty and may be omitted if no validation errors provided for a transaction.
userobject
Represents the user object who has initiated a remittance transaction
Show child attributes
recipientobject
Represents the user object.
Show child attributes
quoteobject
Represents the fee details applied on transaction. These values are referred from quotes.
Show child attributes
charged_amountobject
Represents the amount charged to user.
Show child attributes
converted_amountobject
Represents the amount which is sent to beneficiary after fee deduction.
Show child attributes
recipient_amountobject
Represents the amount the recipient would receive.
Show child attributes
receiving_institutionobject
Object represents receiving institution of recipient to which remittance has been performed.
Show child attributes
additional_dataobject
Additional data required to initiate transaction.
Show child attributes
tosobject
Terms of Service Acceptance
Show child attributes
created_bystring
User id of transaction initiator.
Pattern
^[a-zA-Z0-9]*
created_atstring
Date and time of transaction initiation.
expected_deliverystring
Expected date and time of transaction get success.
updated_atstring
Date and time of the latest update on transaction.
remarksstring
Represents the remittance remarks entered by user while initiating a remittance.
400
Object
Bad Request
| **Code** | **Title** | **Detail** |
| ---------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| invalid_model | Invalid Model | Request body is invalid. |
| quote_expired | Quote Expired | Given quote id is already EXPIRED. Please check and try again. |
| quote_not_confirmed | Quote Not Confirmed | Quote is invalid. Please try with another quote. |
| quote_consumed | Quote Consumed | Given quote id is already CONSUMED. Please check and try again. |
| quote_cancelled | Quote Cancelled | Given quote id is already CANCELLED. Please check and try again. |
| quote_failed | Quote Failed | Quote is invalid. Please try with another quote. |
| quote_id_does_not_match | Quote ID Does Not Match | Quote id does not belong to the user. |
| validation_error | Validation Error | Validation errors. |
| | | Required field. |
| | | Transaction amount must be greater than zero. |
| | | Given quote id is invalid. Please check and try again. |
| limit_error | Limit Error | You have exceeded the sender maximum transaction limit. Maximum amount: {currency} {amount}. |
| | | You have exceeded the unit maximum transaction limit. Maximum amount: {currency} {amount}. |
| | | You have exceeded the receiver maximum transaction limit. Maximum amount: {currency} {amount}. |
| | | Provider's corridor minimum limit breached. Minimum amount: {currency} {min_amount}. |
| | | Provider's corridor maximum limit breached. Maximum amount: {currency} {max_amount}. |
| missing_user_address | Missing User Address | Address information is not available. Please check and try again. |
| user_not_active | User Not Active | User is not active. |
| kyc_not_approved | KYC Not Approved | User KYC is not approved. |
| quote_receiver_currency_does_not_match | Quote And Receiver Currency Does Not Match | Quote currency and receiver currency needs to be same. Please check and try again. |
| quote_receiver_institution_type_does_not_match | Quote And Receiver Institution Type Does Not Match | Receiving institution type in quote and receiver's receiving institute type needs to be same. Please check and try again. |
| quote_receiver_transaction_type_does_not_match | Quote And Receiver Transaction Type Does Not Match | User type and recipient type of quote and transaction needs to be same. Please check and try again. |
| quote_receiver_country_does_not_match | Quote And Receiver Country Does Not Match | Quote's destination country and receiver country needs to be same. Please check and try again. |
| invalid_recipient_id | Invalid Recipient ID | Recipient does not exist. Please provide a valid recipient id. |
| invalid_user_id | Invalid User ID | User does not exist. Please provide a valid user id. |
| need_updation_recipient_data | Need Updation Recipient Data | Recipient data needs to be updated as per the latest recipient form version. |
| quote_user_currency_does_not_match | Quote And User Currency Does Not Match | Invalid user currency. |
| missing_user_wallet | Missing User Wallet | Wallet information is not available. Please check and try again. |
| user_balance_insufficient | User Balance Insufficient | Insufficient balance. Please top up your wallet and retry the transaction. |
| transaction_already_expired | Transaction Already Expired | Transaction expired as quote expired. |
| transaction_already_submitted | Transaction Already Submitted | Quote is already utilised. Please create new quote and try again. |
| transaction_pending_state | Transaction Pending State | Quote is already utilised. Please create new quote and try again. |
| transaction_already_complete | Transaction Already Complete | Quote is already utilised. Please create new quote and try again. |
| remittance_receiver_is_risky | Remittance Receiver Is Risky | Remittance receiver have exceeded the risk and compliance threshold and transaction was automatically cancelled. |
Response Attributes
idstring Required
Unique hash-id for the error message
statusinteger Required
Error response status code
codestring Required
Error response code
titlestring Required
Error response title
detailstring Required
Error response detail
sourcearray,string
Source defines the multiple error messages
Show child attributes
timestampstring Required
Response timestamp
401
Object
Unauthorized Request
| **Code** | **Title** | **Detail** |
| ---------------------------| ----------------------| ---------------------------------------------------|
| token_required | Token Required | Access denied due to invalid token on header. |
| invalid_tenant | Invalid Tenant | Access denied due to invalid tenant code. |
Response Attributes
idstring Required
Unique hash-id for the error message
statusinteger Required
Error response status code
codestring Required
Error response code
titlestring Required
Error response title
detailstring Required
Error response detail
sourcearray,string
Source defines the multiple error messages
Show child attributes
timestampstring Required
Response timestamp
403
Object
Forbidden
| **Code** | **Title** | **Detail** |
| ---------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| restricted_resource | Restricted Resource | Access denied to the resource. If your access key and source IP is correct, it would be because of `X-Auth-User-ID` is not passed on header. |
Response Attributes
idstring Required
Unique hash-id for the error message
statusinteger Required
Error response status code
codestring Required
Error response code
titlestring Required
Error response title
detailstring Required
Error response detail
sourcearray,string
Source defines the multiple error messages
Show child attributes
timestampstring Required
Response timestamp
404
Object
Not Found
| **Code** | **Title** | **Detail** |
| --------------------------| ---------------------- | -------------------------------------|
| resource_not_found | Resource Not Found | The requested URL was not found. |
Response Attributes
idstring Required
Unique hash-id for the error message
statusinteger Required
Error response status code
codestring Required
Error response code
titlestring Required
Error response title
detailstring Required
Error response detail
sourcearray,string
Source defines the multiple error messages
Show child attributes
timestampstring Required
Response timestamp
500
Object
Internal Server Error
| **Code** | **Title** | **Detail** |
| ---------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| generic_error | General Error | General application error. |
