BusinessPersonal
Documentation

Payout

Suggest Edits

Introduction

The Payout API module enables in-store applications to payout a transaction in cash to the intended receive customer. Virtual wallets can also use the payout endpoints to "receive and redirect" a transaction and move funds into the receive customer's wallet.



API sequence

The Payout API module comprises of six synchronous endpoints. There are two general models for paying out funds and the API sequence is as follows:

This is the standard model for paying out a transaction and consists of a three-part API call sequence: retrieve, update and commit a transaction. In this model, the transaction can look up a transaction for payout, before updating it with consumer and transactional information. The transaction is finally committed and funds are paid out to the customer.

  1. Retrieve a transaction | GET /payout/v1/transacitons/{transacitonId}

To retrieve a transaction for payout, the application must use referecnceNumber as a query parameter to retrieve the transaction. The endpoint returns a 200 OK HTTP Status the transactionId resource, status and transactional information. This is to be validated by the in-store associate and receive customer for KYC purposes.

NOTE: The referenceNumber is a eight-digit numeric string and is generated at the time of transfer. It's the customer's unique identifier of the transaction. The receive customer typically enters the reference number in the application to lookup and retrieve a transaction for payout.

  1. Update a transaction | PUT /payout/v1/transactions/{transactionId}

The application must use the transactionId resource as a path parameter and update it with information about the recieve customer. The endpoint will validate all details and successfully respond with a 200 OK HTTP status and 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 scenario. The application must build to handle various error codes scenarios and allow the user to correct all errors. Learn more

  1. Commit a transaction | PUT /payout/v1/transactions/{transactionId}/commit

The application must use the commit API to execute the payout and the endpoint will successfully respond with a 200 OK HTTP status For in-store applications, the funds can be paid out in cash. For digital transactions, the funds can be redirected to a bank account/wallet. The transaction status will move to "RECEIVED" and funds will be marked for settlement.

API sequence diagram

Transfer sequence diagram 1

This is an advanced model for paying out a transaction that uses the ‘Retrieve Additional Information’ endpoint to securely provide data to the partner for regulatory purposes. This model is to be used only in countries where regulation stipulates additional transactional information is needed at time of payout. The API is only available upon business request and must be called in the following sequence:

  1. Retrieve a transaction | GET /payout/v1/transacitons/{transacitonID}

To retrieve a transaction for payout, the application must use referecnceNumber as a query parameter to retrieve the transaction. The endpoint returns a 200 OK HTTP status the transactionId resource, status and transactional information. This is to be validated by the in-store associate and receive customer for KYC purposes.

NOTE: The referenceNumber is a eight-digit numeric string and is generated at the time of transfer. It's the customer's unique identifier of the transaction. The receive customer typically enters the reference number in the application to look up and retrieve a transaction for payout.

  1. Retrieve Additional information | GET /payout/v1/transactions/{transcitonId}/additionalInformation

In some countries, regulation may stipulate additional transactional information is needed at time of payout. The GET: Retrieve Additional Information endpoint is available upon business request and securely provides additional information to the partner for regulatory purposes.

  1. Update a transaction | PUT /payout/v1/transactions/{transactionId}

The application must use the transactionId resource as a path parameter and update it with information about the recieve customer. The endpoint will validate all details and successfully respond with a 200 OK HTTP status and 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 scenario. The application must build to handle various error codes scenarios and allow the user to correct all errors. Learn more

  1. Commit a transaction | PUT /payout/v1/transactions/{transactionId}/commit

The application must use the commit API to execute the payout and the endpoint will successfully respond with a 200 OK HTTP status For in-store applications, the funds can now be paid out in cash. For digital transactions, the funds can be redirected to bank account/wallet. The transaction status will move to "RECEIVED" and funds will be marked for settlement.

API sequence diagram

alt="Transfer sequence diagram 2">


Advanced Features

The Payout API module is packed full of Advanced Features and we included detailed guides on how to get the most out of your integration:

  • In some countries, regulation may stipulate additional transactional information is needed at time of payout. The GET: Retrieve Additional Information endpoint is available upon business request and securely provides additional information to the partner for regulatory purposes.

  • The Payout Module also PUT: Reverse a Transaction endpoint, should the application need to move a transaction back in to available status and no longer continue with the payout.


Endpoints

NameMETHODURLDescription
Retrieve a TransactionGETpayout/v1/transactionsLookup a transaction by reference number for payout
Update a TransactionPUTpayout/v1/transaction/{transactionId}Updates a payout transaction and verifies whether the information collected about the sender is sufficient for identification and regulatory purposes.
Retrieve a Additional InformationGETpayout/v1/transactions/{transactionId}/additionalInformationLookup a transaction by transactionId for additional compliance information
Commit a TransactionPUTpayout/v1/transactions/{transactionId}/commitComplete the transaction when the validation indicates the transaction is ready for commit.


Example User Journey

1 - Lookup a Transaction

The cashier looks up a transaction by the reference number provided by the customer for payout.

2 - Transaction Summary

A transfer summary is provided and is ready for payout.

3 - Verify Receiver Details

The cashier verifies the receiver information and collects additional information about the receiver as required.

4 - Transfer complete

The cashier completes and pays out the transaction in cash and provides a receipt.


Updated about 1 month ago

Moneygram Logo
Media Center Privacy Center Terms of Use Become an agent MoneyGram Money Transfer
LinkedIn Facebook Instagram Twitter Youtube

Authorized to do business in all 50 states, D.C. and all U.S. territories, NMLS #898432. Licensed as a Money Transmitter by the New York State Department of Financial Services. Massachusetts Check Seller License #CS0025, Foreign Transmittal License #FT89432. MoneyGram. MoneyGram Payment Systems, Inc. is registered as a Money Services Business under FinCEN, Registration #. 31000221116940. MoneyGram and the Globe are marks of MoneyGram. All other marks are the property of their respective owners. © 2023 MoneyGram