Disbursement
Introduction
The Disbursement API module allows a business user to disburse funds cross-boarder, business-to-consumer (b2c).
An application can use the Disbursement endpoints to securely move funds to over 200 countries and in multiple currencies. The APIs enable funds to be picked up in cash or deposited directly to their bank account/wallet/card, giving businesses the greater choice on how they move funds.
API Sequence
The Business API module comprises of four synchronous endpoints. The general process for disbursing business funds is as follows:
This is the standard model for disbursing B2C funds and consists of a three API call sequence: quote, update and commit a transaction. This model is applicable to partners wanting to creates single business transaction. In this model, MoneyGram will provide a quote which will typically comprise of a fee, Fx, currencies and service options. The business will next update the transaction with transactional information, before finally committing the transaction for disbursement.
- Quote a transaction |
POST /disbursement/v1/transactions/quote
POST /disbursement/v1/transactions/quoteTo quote a transaction, the application must include destination country, amount and currency to the API request. The endpoint will successfully respond with a 200 OK HTTP Status and array of quotes will return, typically containing send amounts, receive amounts, fees/fx and totals
NOTE: the Quote endpoint creates a transactionId resource for each quote listed in the response. Once the Customer has selected their quote, the application must use the corresponding transactionId to Update and commit the resource to MoneyGram.
- Update a transaction |
PUT /disbursement/v1/transactions/{transactionId}
PUT /disbursement/v1/transactions/{transactionId}The application must continue with one quote and update the transactionId resource with sender, receiver and transactional information. If the transaction is to be deposited to a bank/wallet/card, the target account information must also be provided. The endpoint will validate all details and successfully respond with a transaction summary.
NOTE: MoneyGram will perform real-time validation and compliance screening upon the submitted request. Depending on the results of the validation, the endpoint will respond with a pass or fail scenarios. The application must build to handle various error code scenarios and allow the user to correct all errors. Learn More
- Commit a transaction |
PUT /disbursement/v1/transactions/{transactionId}/commit
PUT /disbursement/v1/transactions/{transactionId}/commitThe application must use the commit API to execute the transfer. The endpoint will successfully respond with the transaction reference number, which can be used by the customer to pick-up the funds in cash or track the progress of their transfer. The funds will also be marked for settlement.
API Sequence Diagram
This is an advanced model for disbursing B2C funds and consists of two API call sequence for faster transaction processing: create and commit a transaction. This model is applicable to partners wanting to process business transactions by batch. In this model, the partner simply creates a transaction by providing transactional information, before finally committing the transaction.
- Create a transaction |
POST /disbursement/v1/transactions
POST /disbursement/v1/transactionsTo create batch transactions the partner uploads file to MoneyGram’s secure server with transaction and beneficiary information. MoneyGram processes a transaction for each recipient and generates a response file with the reference numbers for each transaction. MoneyGram provides the reponse file to the partner and the partner distributes the reference numbers to the recipients. To Create a transaction, the application must include the sender, receiver and all required transactional information. If the transaction is to be deposited to a bank, wallet, or card, the target account information must also be provided. The endpoint will validate all the details and successfully respond with a confirmed transaction that is ready for commit.
NOTE: The Create endpoint generates a transactionId resource for each . The application must use the this transactionId to commit the resource to MoneyGram.
- Commit a transaction |
PUT /disbursement/v1/transactions/{transactionId}/commit
PUT /disbursement/v1/transactions/{transactionId}/commitThe application must use the commit API to execute the transfer. The endpoint will successfully respond with the transaction reference number, which can be used by the customer to pick-up the funds in cash or track the progress of their transfer. The funds will also be marked for settlement.
API Sequence Diagram
Endpoints
| Name | HTTP Method | Endpoints | Description |
|---|---|---|---|
| Quote a transaction | POST | /transactions/quote | Provides quotes with service option, fees and exchange rate for available payout options. |
| Create a transaction | POST | /transactions | Creates payout transaction with specific payout option and verifies whether the information collected about the sender is sufficient for identification and regulatory purposes. |
| Update a transaction | PUT | /transaction/{transactionId} | Update payout transaction and verify whether the information collected about the sender is sufficient for identification and regulatory purposes. |
| Commit a transaction | PUT | /transaction/{transactionID}/commit | Complete the transaction when the validation indicates the transaction is ready for commit |
Example User Journeys
1 - Get a Quote
MoneyGram provides payout options along with a competitive transfer fee and foreign exchange rate.
2 - Enter Recipient Information
3 - Transfer Complete
1 - Upload Payment File
Partner uploads file to MoneyGram’s secure server with transaction and beneficiary information.
2 - Transactions are Procesed
3 - Response file Generated
4 - Receive and Notify
5 - Recipient Receives Funds
Updated over 1 year ago
