Introduction

Welcome to Machnet’s API documentation portal. This API document outlines the process for implementing Machnet’s Unified Money Transfer Platform into your application.

Synchronize Default Data

Prior to registering new senders and/or initiating a transfer, you will need to either save or manage the data provided by the following APIs.

1. Countries
2. States
3. Cities
4. Banks and Branches
5. Exchange Rates

Authentication

Machnet shall provide you with a set of keys viz., CLIENT_ID and CLIENT_SECRET. You will need to add these values in every API request header. These values should never be used publicly and should be stored properly in an encrypted format.

Header	Client Keys
X-Client-Id	CLIENT_ID
X-Client-Secret	CLIENT_SECRET

Widget

Machnet provides a widget for process such as user KYC verification, addition of funding source, Transaction invoice and Tier upgrade. This section details the widget integration process. Please note that you will need to register customers on our end before initializing the widget.

Widget Setup

You will need to follow the steps mentioned below to setup the widget.

1. Include the Widget Script

   <script src="https://sandbox.api.machpay.com/v2/widget/widget.js" charset="utf-8"></script>
   

2. Create a div where widget needs to be placed.

   <div id="widget-root"></div>
   

3. Initialize the Widget

   <script>
     var widget = new MachnetWidget({
       elementId: "widget-root",
       senderId: "62018cb0-e183-4a72-a691-844c213a693a",
       width: "100%",
       height: "200px",
       type: "kyc",
       locale: "ko",
       multiStep: true,
       stylesheet: "https://example.com/mystyle.css",
       token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZW5kZXJJZCI6Ik1qaGtZbVU1WkRBdFpURXlNQzAwTkRreExXSTRNREl0WVRCak16ZGlaV1EzWTJKbFxyXG4iLCJleHAiOjE1NjE2NDExNTcsIm10b0lkIjoiT1FcclxuIn0.f0yKZUt35VC_Mo2D8vk0Cbc_D-c2zAv9MAtmQi2zah8",
     });
     widget.init();
   </script>
   

   Property Name	Required	Type	Description
   elementId	Yes	String	Target element where widget will be rendered.
   senderId	Yes	String	senderId for whom the widget should be rendered.
   transactionId	No	String	transactionIdwhen initializing the Invoice widget
   bankId	No	String	bankId for which credential needs to be updated
   width	Yes	Standard Size Dimension eg. 100px, 100%, 100em	Width of widget
   height	Yes	Standard Size Dimension e.g. 100px, 100%, 100em	Height of widget
   type	Yes	String	Type of Widget. kyc, bank, card, tier, invoice For example, If kyc is provided then KYC widget will be rendered.
   locale	No	String	By default, this is set to English, For Korean pass ko and for English pass en. If left blank or invalid locale is sent it will fall back to default language.
   stylesheet	No	URL	This stylesheet will override the default design of the widget.
   token	Yes	String	Unique Token that needs to be generated using Generate Widget Token API.
   multiStep	No	boolean(true or false)	Configuration to display the widget in a single or multiple form

4. Add an Event Handler

   Widget will trigger an event anytime there is changes in a resource. To listen to the events generated by the widget include below code snippet,

   window.addEventListener("message", function (e) {
     <!--Here e.data holds the information about the event triggered. 
        e.data.type    = kyc || bank || tier
        e.data.status  = eventName
        e.data.message = additional message
   
    -->
     if(e.data.status === 'eventName'){
       //your action
     }
   });
   

   Event Name	Widget Type	Description
   VERIFIED	kyc	KYC process is completed and user is verified.
   RETRY	kyc	The user is moved to retry state.
   PENDING	kyc	Document verification in progress.
   DOCUMENT_NEEDED	kyc	User needs to upload a document.
   FAILED	kyc	User document verification has failed.
   RETRY	kyc	Document not in prescribed format. The user needs to resubmit their information.
   SUSPENDED	kyc	The user has been suspended.
   APPROVED	kyc	The user document has been approved.
   BANK_ADDED	bank	Sender’s Bank Linking process is complete.
   BANK_ERROR	bank	Error while adding sender’s bank.
   CARD_ADDED	card	Sender’s Card Linking process is complete.
   CARD_ERROR	card	Error while adding sender’s card.
   TIER2_REQUESTED	tier	Tier 2 request sent successfully.
   TIER3_REQUESTED	tier	Tier 3 request sent successfully.
   TIER_REQUEST_FAILED	tier	Error while upgrading sender’s tier.

Applying Custom CSS to Widget

You need to create a CSS file based on the DOM structure and then create a stylesheet based on the required changes. If you load the stylesheet during the widget initialization, the changes will be reflected accordingly.

Know Your Customer Widget (Sender Identity Verification Widget)

This widget can be triggered by passing widget type as kyc. Please note that the senders would not be allowed to change any of their details once their KYC has been verified.

Link/Add Sender Bank Widget

This widget would be accessible when the sender’s KYC status is other than UNVERIFIED or SUSPENDED on Machnet platform. This widget can be triggered by passing widget type as bank.

Link/Add Sender Debit Card Widget

This widget would be accessible after the sender’s KYC status is other than UNVERIFIED or SUSPENDED on Machnet platform. This widget can be triggered by passing widget type as card.

Change Sender Bank Credentials

In case the sender bank credentials have been changed, the sender is required to re-login to their account with updated credentials. This event is notified to the affiliate through a webhook with event name sender_bank_login_required. In this case, the widget needs to be initialized using the bankId.

Upgrade Tier Widget

If the sender wants to transfer more funds than the default limits then they will need to upgrade to a higher tier. For this, they will need to provide additional information. This widget can be triggered by passing widget type as “tier”. Please refer to the Compliance section in Machnet White Label Integration Guide for more details.

Invoice Widget

The Invoice Widget will be used to generate MSB specific invoice once a transaction has been created. This widget will only be accessible after the transaction has been created on Machnet platform and can be triggered by passing the widget type as invoice and the respective transactionId.

Initialize the Invoice Widget.

<script>
  var widget = new MachnetWidget({
    elementId     : "widget-root",
    senderId      : "d084fa75-fad4-40fc-a2b8-7996ea56d044",
    width         : "100%",
    height        : "2000px",
    type          : "invoice",
    locale        : "en",
    transactionId : "rektaa75-fad4-40fc-a2b8-7996ea56d044",
    token         : "very.long.token"
 });
 widget.init();
</script>

Generate token to initialize widget

In order to initialize the widget, you will need to first generate a Widget Token, which will be valid for an hour. You will need to pass this token along with the Sender ID to widget initialization snippets.

GET /v2/senders/{senderId}/widget-token

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.

Request

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/widget-token \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "token": "string",
  "sender_id": "UUID",
  "expiry_minutes": 60
}

Countries

This API provides the list of source and destination countries supported by Machnet platform. The value returned by this API will be used for setting the exchange rates.

Country Object

Name	Type	Description
id	integer
name	string	The full name of the country.
three_char_code	string	The 3-character ISO code of the country.
two_char_code	string	The 2-character ISO code of the country.
phone_code	integer	The county code used for international dialing.
currency	object	Currency object.

Currency Object

Name	Type	Description
code	string	The ISO code of the currency used in the country.
name	string	The name of the currency used in the country.
symbol	string	The currency symbol used in the country.

List All Countries

GET /v2/countries

Returns list of all countries and related information.

Request

curl -X GET https://sandbox.api.machpay.com/v2/countries \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "result": [
    {
      "id": 0,
      "name": "string",
      "three_char_code": "string",
      "two_char_code": "string",
      "phone_code": 0,
      "currency": {
        "code": "string",
        "name": "string",
        "symbol": "string"
      }
    }
  ]
}

Get Country By Id

GET /v2/countries/{countryId}

Returns country information based on countryId.

Request

curl -X GET https://sandbox.api.machpay.com/v2/countries/{countryId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "id": 0,
  "name": "string",
  "three_char_code": "string",
  "two_char_code": "string",
  "phone_code": 0,
  "currency": {
    "code": "string",
    "name": "string",
    "symbol": "string"
  }
}

States

This API provides the list of states supported in a country.

State Object

Name	Type	Description
id	integer	The ID of the state.
name	string	The name of the state.
code	string	2 character ISO code of the state.
country_id	integer	The ID of the country.

List All Available States

Get all states associated with all countries enabled for the affiliate.

If countryId is provided in the query string, only the states for that country is returned.

GET /v2/states

Request Parameters - Query String

Parameter	Required	Type	Description
countryId	No	Integer	Country Id

Request

curl -X GET https://sandbox.api.machpay.com/v2/states \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "result": [
    {
      "id": 0,
      "name": "string",
      "code": "string",
      "country_id": 0
    }
  ]
}

Get State By Id

Returns state information based on given id(stateId).

GET /v2/states/{stateId}

Request Parameters - URL

Parameter	Required	Type	Description
stateId	Yes	Integer	State Id

Request

curl -X GET https://sandbox.api.machpay.com/v2/states/{stateId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "id": 0,
  "name": "string",
  "code": "string",
  "country_id": 0
}

Cities

This API provides the list of states supported in a country.

City Object

Name	Type	Description
id	integer	The ID of the state.
name	string	The name of the state.
country_id	integer	The ID of the country.
state_id	integer	The ID of the state.

List Available Cities for Countries/States

GET /v2/cities

Two parameters - countryId and stateId can be used to filter the list of cities. Both parameters are optional.

Request Parameters - Query String

Parameter	Required	Type	Description
countryId	No	Integer	Country Id
stateId	No	Integer	State Id

Request

curl -X GET https://sandbox.api.machpay.com/v2/cities \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "result": [
    {
      "id": 0,
      "name": "string",
      "country_id": 0,
      "state_id": 0
    }
  ]
}

Exchange Rates

This API is used to set the exchange rates between source and destination country. For sandbox environment the exchange rate would be set automatically with a test value. However, in production, in order to set the exchange rates, you will need to follow the procedure defined in the Machnet White Label Integration Guide.

Exchange Rate Object

Name	Type	Description
id	UUID	ID
source_currency	string	ISO code of the source currency.
source_currency_name	integer	Name of the source currency.
destination_currency	string	ISO code of the destination currency.
destination_currency_name	string	Name of the destination currency.
rate	number	Exchange rate.
active_from	datetime	Date/time when the exchange rate was created.
expired_at	datetime	NULL.

Get Exchange Rates

Fetch Latest Approved Exchange Rates for Affiliate enabled corridor. For instance, USA to Korea, USA to India, USA to Nepal. Exchange rates for specific destinations can also be fetched using a query parameter destinationCurrency.

The destinationCurrency accepts three-char ISO currency code of the destination country.

GET /v2/exchangerates

Request Parameters - Query String

Parameter	Required	Type	Description
sourceCurrency	No	String	The 3-character ISO code for the currency. If sourceCurrency is not set, USD will be used as the source currency.
destinationCurrency	No	String	The 3-character ISO code for the currency. If destinationCurrency is not set, the exchange rate of the MTO is returned.

Request

curl -X GET https://test.api.machpay.com/v2/exchangerates \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "result": [
    {
      "id": "string",
      "source_currency": "string",
      "source_currency_name": "string",
      "destination_currency": "string",
      "destination_currency_name": "string",
      "rate": 0.01,
      "active_from": "2019-06-26T05:34:40Z",
      "expired_at": "2019-06-26T05:34:40Z"
    }
  ]
}

Set Exchange Rate

Set Exchange Rate for Corridor Specified by Source Currency and Destination Currency

POST /v2/exchangerates

Request Parameters - Body

Parameter	Required	Type	Description
source_currency	No	String	The 3-character ISO code for the currency. If sourceCurrency is not set, USD will be used as the source currency.
destination_currency	Yes	String	The 3-character ISO code for the currency.
rate	Yes	Decimal	The exchange rate from the source currency to the destination currency.

Request

curl -X POST https://sandbox.api.machpay.com/v2/exchangerates \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret' \
  -D { \
      "source_currency": "string", \
      "destination_currency": "string", \
      "rate": 0 \
    }

Response

{
  "id": "string",
  "source_currency": "string",
  "source_currency_name": "string",
  "destination_currency": "string",
  "destination_currency_name": "string",
  "rate": 0.01,
  "active_from": "2019-06-26T05:34:40Z",
  "expired_at": "2019-06-26T05:34:40Z"
}

Banks and Branches

Bank Object

Name	Type	Description
id	integer	ID
name	string	Name of the bank.
country	string	3-character ISO code of the country.
branches	List	List of branch objects.

Branch Object

Name	Type	Description
bank_id	integer	Bank ID
bank_name	string	Name of the bank.
branch_id	integer	Branch ID.
branch_name	string	Name of the branch.
address	string	Branch address.
city	string	Branch city.
state	string	Branch state or province.

Get All Banks

GET /v2/banks

Request Parameters - Query String

Parameter	Required	Type	Description
countryId	No	integer	Country ID.

Request

curl -X GET https://sandbox.api.machpay.com/v2/banks \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "id": 00,
  "name": "Test Bank",
  "country": "NGA",
  "branches": [
    {
      "id": 00,
      "name": "Test Bank Branch"
    }
  ]
}

Get Bank by ID

GET /v2/banks/{bankId}

Request Parameters - Query String

Parameter	Required	Type	Description
bankId	Yes	integer	Bank ID

Request

curl -X GET https://sandbox.api.machpay.com/v2/banks/{bankId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "id": 10,
  "name": "Test Bank",
  "country": "NGA",
  "branches": [
    {
      "id": 20,
      "name": "Test Bank Branch"
    }
  ]
}

Payers

The payer id is required for creating transactions with delivery_method as CASH_PICKUP and HOME_DELIVERY. Here, the receiver can collect the transferred amount from any of the payer's location in the country.

Payer Object

Name	Type	Description
id	long	ID
name	string	Name of the Payer.
country	string	3-character ISO code of the country
code	string	Payer Code
address	string	Address of the Payer.
phone_number	string	Contact Number of the Payer.
website	string	Website of the Payer.
network_limit	string	Txn limit of the Payer.
delivery_method	string	Delivery method of the Payer.

Get All Payers

GET /v2/payers

Request Parameters - Query String

Parameter	Required	Type	Description
country	No	string	Three char country code.

Request

curl -X GET https://sandbox.api.machpay.com/v2/payers \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
    "results": [
        {
            "id": 1,
            "name": "Acme - REPUBLIC OF ARMENIA",
            "country": "ARM",
            "website": "",
            "delivery_method": "CASH_PICKUP"
        }
    ],
    "paging": {
        "total_count": 1
    }
}

Get Payer by ID

GET /v2/payers/{payerId}

Request Parameters - Query String

Parameter	Required	Type	Description
payerId	Yes	long	Payer ID

Request

curl -X GET https://sandbox.api.machpay.com/v2/payers/{payerId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
    "id": 1,
    "name": "Acme - REPUBLIC OF ARMENIA",
    "receiving_currency": "USD",
    "code": "ARM0001",
    "country": "ARM",
    "address": "VAHRAM PAPAZYAN 12",
    "phone_number": "+374 10 27-72-85",
    "website": "",
    "network_limit": [],
    "delivery_method": "CASH_PICKUP"
}

Sender

You will first need to consume the Sender Registration API to be able to initialize the widget for further processing. You will need to provide the sender’s basic information via this API such as the sender's first name, middle name, last name, mobile phone number, email and state code. The State Code can be obtained from the State API.

The response of this API contains that Sender ID which should be stored at your end as it will be used when calling other APIs.

Sender Object

Name	Type	Description
id	UUID	Sender ID
first_name	string	The first name of the sender.
middle_name	string	The middle name of the sender.
last_name	string	The last name of the sender.
mobile_phone	string	10-15 digit mobile phone number of sender.
email	string	The email address of the sender.
state	string	2-letter ISO code of the sender's state.
current_tier	string	Enumerated value LEVEL1, LEVEL2, LEVEL3.
status	string	Sender's KYC status defined by enumerated value VERIFIED, IN_PROGRESS, UNVERIFIED, DOCUMENT, SUSPENDED, RETRY, REUPLOAD, REVIEW_PENDING, RETRY_REQUESTED, DOCUMENT_REQUESTED.
requested_fields	list	List of field information if required by admin for sender kyc process. Enumerated value SENDER_ID_INFO, SENDER_SOURCE_OF_FUND, SENDER_PROOF_OF_ADDRESS, SENDER_FULL_SSN.
cip_failure_reasons	list	List of reasons in case of sender kyc failure.

Register Sender

Register a new sender.

POST /v2/senders

Request Parameters - Body

Sender

Name	Required	Type	Description
first_name	Yes	string	The first name of the sender.
middle_name	No	string	The middle name of the sender.
last_name	Yes	string	The last name of the sender.
mobile_phone	Yes	string	10-15 digit mobile phone number of sender.
email	Yes	string	The email address of the sender.
state	Yes	string	2-letter ISO code of the sender's state.

Request

curl -X POST https://sandbox.api.machpay.com/v2/senders \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret' \
  -d { \
      "first_name": "string", \
      "middle_name": "string", \
      "last_name": "string", \
      "mobile_phone": "string", \
      "email": "user@example.com", \
      "state": "string" \
  }

Response

{
  "id": "UUID",
  "first_name": "string",
  "middle_name": "string",
  "last_name": "string",
  "mobile_phone": "string",
  "email": "user@example.com",
  "state": "string",
  "current_tier": "string",
  "status": "string"
}

Get Sender By Id

Fetch detail of a single sender.

GET /v2/senders/{senderId}

Request Parameters

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.

Request

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "id": "UUID",
  "first_name": "string",
  "middle_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "state": "string",
  "current_tier": "string",
  "status": "string",
  "mobile_phone": "string",
  "requested_fields": [
          "SENDER_SOURCE_OF_FUND"
      ],
  "cip_failure_reasons": [
          "No public record found"
      ]
}

Sender Funding Accounts

The sender can add either bank account or link debit cards through the Bank and Card widget respectively. These accounts are collectively described as senders funding accounts. The details of the account would be available via this API. The response can be stored on your end for further operations such as Create Transaction, Remove Funding Account etc.

1. Sender Banks
2. Sender Debit Cards

Sender Banks

Sender Funding Account Object for Banks

Name	Type	Description
id	UUID	Sender Funding Account ID
sender_id	UUID	Sender ID associated with the funding account
funding_source_name	string	Name of the funding account
institution_name	string	Name of the institution/bank associated with the account
account_type	string	Type of bank account. Enumerated value CHECKING or SAVINGS
account_holder_name	string	The name in the bank account.
verification_status	string	Enumerated value PENDING, VERIFIED, FAILED, LOGIN_REQUIRED
funding_source_type	string	Enumerated value BANK

Sender Debit Cards

Sender Funding Account Object for Debit Card

Name	Type	Description
id	UUID	Sender Funding Account ID
sender_id	UUID	Sender ID associated with the funding account
funding_source_name	string	Name of the funding account
nick_name	string	Name given to identify the account through the widget
institution_name	string	Name of the institution/bank associated with the account
regulated	boolean	Represents if the card is regulated or not
network	string	name of the CARD Network.
funding_source_type	string	Enumerated value CARD

Get Sender Funding Account By Id

Returns the details of the funding account associated with the sender.

GET /v2/senders/{senderId}/funding-sources/{fundingAccountId}

Request Parameters

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.
fundingAccountId	Yes	UUID	Funding Account ID.

Request

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/funding-sources/{fundingSourceId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

If the funding account is a bank:

{
    "id": "string",
    "sender_id": "string",
    "funding_source_name": "string",
    "institution_name": "string",
    "account_type": "string",
    "account_holder_name": "string",
    "verification_status": "string",
    "funding_source_type": "BANK"
}

If the funding account is a debit card:

{
    "id": "string",
    "sender_id": "string",
    "nick_name": "string",
    "funding_source_name": "string",
    "institution_name": "string",
    "funding_source_type": "CARD",
    "regulated": false,
    "network": "string"
}

Delete Sender Funding Account

Deletes the funding account information associated with the sender.

DELETE /v2/senders/{senderId}/funding-sources/{fundingAccountId}

Request Parameters

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.
fundingAccountId	Yes	UUID	Funding Account ID.

Request

curl -X DELETE https://sandbox.api.machpay.com/v2/senders/{senderId}/funding-sources/{fundingAccountId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Get All Funding Accounts

Returns all the funding accounts associated with the sender.

GET /v2/senders/{senderId}/funding-sources

Request Parameters

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.

Request

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/funding-sources \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "result": [
   {
        "id": "string",
        "sender_id": "string",
        "funding_source_name": "string",
        "institution_name": "string",
        "account_type": "string",
        "account_holder_name": "string",
        "verification_status": "string",
        "funding_source_type": "BANK"
    } , {
        "id": "string",
        "sender_id": "string",
        "nick_name": "string",
        "funding_source_name": "string",
        "institution_name": "string",
        "funding_source_type": "CARD",
        "regulated": false,
        "network": "string"
    }
  ]
}

For fetching accounts according to funding source type, you can pass a query parameter.

For banks, GET /v2/senders/{senderId}/funding-sources?type=BANK

For cards, GET /v2/senders/{senderId}/funding-sources?type=CARD

Recipients

After a sender has been successfully added, you can proceed towards adding recipient for the sender. You will need to register at least one recipient to be able to initiate a transfer.

Recipient Object

Name	Type	Description
id	UUID	Recipient ID
sender_id	UUID	Sender ID
first_name	string	The first name of the recipient.
middle_name	string	The middle name of the recipient.
last_name	string	The last name of the recipient.
country	string	ISO code of the recipient's country.
address_line1	string	Street address of the recipient.
address_line2	string	Second line of the street address.
city	string	Recipient's city.
postal_code	string	Zip code of the recipient.
province	string	Name of the state or province.
email	email	Recipient's email address.
document	string
home_phone	string	Home phone number.
mobile_phone	string	Mobile phone number.
work_phone	string	Work phone number.
date_of_birth	date	Date of birth.
occupation	string
sender_relationship	string	Enumerated value Aunt, Brother, Brother in Law, Cousin, Daughter, Father, Father in Law, Friends, Grand Father, Grand Mother, Husband, Mother, Mother in law, Nephew, Niece, Self, Sister, Sister in Law, Son, Uncle, Wife, Others
status	string	Enumerated value - VERIFIED, UNVERIFIED
available_payout_methods	list	list of Enumerated value - BANK_DEPOSIT, CASH_PICKUP, WALLET, HOME_DELIVERY. BANK_DEPOSIT is present by default

Get All Recipients

You can list recipients using this API. This API returns all recipients associated with the provided sender along with the recipient's information which will be useful when initiating transactions from the sender to the same recipient.

GET /v2/senders/{senderId}/recipients

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.

Request

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/recipients \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "result": [
    {
      "id": "UUID",
      "sender_id": "string",
      "first_name": "string",
      "middle_name": "string",
      "last_name": "string",
      "country": "string",
      "address_line1": "string",
      "address_line2": "string",
      "city": "string",
      "postal_code": "string",
      "province": "string",
      "email": "string",
      "document": "string",
      "home_phone": "string",
      "mobile_phone": "string",
      "work_phone": "string",
      "date_of_birth": "string",
      "occupation": "string",
      "sender_relationship": "string",
      "status": "string"
    }
  ]
}

Add Recipient

This API allows you to save Recipient for Given Sender. You will need to provide recipient’s basic information via this API. The response contains a unique Recipient ID that you can store on your end.

The field available_payout_methods shows the list of payout method that are available from the recipient while creating a transaction. For a recipient to be eligible for BANK_DEPOSIT or CASH_PICKUP or WALLET or HOME_DELIVERY, available_payout_methods must contain the payout method.

BANK_DEPOSIT is enabled by default for all receivers and they can receive the amount if their bank information is added.

For a recipient to be eligible for CASH_PICKUP the field enable_cash_pickup must be set to true while creating or updating the recipient. If the enable_cash_pickup is set to true, additional information about the receiver which were optional may be required based on the receiver's country.

If an affiliate is configured for Mobile Wallet as delivery, WALLET is enabled for all the receiver for that affiliate.

If an affiliate is configured for Home Delivery as delivery, HOME_DELIVERY is enabled for all the receiver for that affiliate.

Use one of the following values for sender_relationship: Aunt, Brother, Brother in Law, Cousin, Daughter, Father, Father in Law, Friends, Grand Father, Grand Mother, Husband, Mother, Mother in Law, Nephew, Niece, Self, Sister, Sister in law, Son, Uncle, Wife

POST /v2/senders/{senderId}/recipients

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.

Request Parameters - Body

Parameter	Required	Type	Description
first_name	Yes	String	The first name of the recipient.
middle_name	No	String	The middle name of the recipient.
last_name	Yes	String	The last name of the recipient.
country	Yes	String	ISO code of the recipient's country
address_line1	Yes	String	Street address of the recipient.
address_line2	No	String	Second line of the street address.
city	Yes	String	Recipient's city.
postal_code	Yes	String	Zip code of the recipient.
province	Yes	String	Name of the state or province.
email	No	Email	The email address of the recipient.
document	No	String
home_phone	No	String	Home phone number.
mobile_phone	No	String	Mobile phone number.
work_phone	No	String	Work phone number.
date_of_birth	No	Date	Date of birth.
occupation	No	String	Occupation.
sender_relationship	Yes	String	Enumerated value Aunt, Brother, Brother in Law, Cousin, Daughter, Father, Father in Law, Friends, Grand Father, Grand Mother, Husband, Mother, Mother in law, Nephew, Niece, Self, Sister, Sister in Law, Son, Uncle, Wife
enable_cash_pickup	No	boolean	Set the flag to true for enabling CASH_PICKUP

Request

curl -X POST https://sandbox.api.machpay.com/v2/senders/{senderId}/recipients \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret' \
  -d { \
    "first_name": "string", \
    "middle_name": "string", \
    "last_name": "string", \
    "country": "string", \
    "address_line1": "string", \
    "address_line2": "string", \
    "city": "string", \
    "postal_code": "string", \
    "province": "string", \
    "email": "string", \
    "document": "string", \
    "home_phone": "string", \
    "mobile_phone": "string", \
    "work_phone": "string", \
    "date_of_birth": "string", \
    "occupation": "string", \
    "sender_relationship": "string" \
    "enable_cash_pickup": true \
  }

Response

{
  "id": "UUID",
  "sender_id": "string",
  "first_name": "string",
  "middle_name": "string",
  "last_name": "string",
  "country": "string",
  "address_line1": "string",
  "address_line2": "string",
  "city": "string",
  "postal_code": "string",
  "province": "string",
  "email": "string",
  "document": "string",
  "home_phone": "string",
  "mobile_phone": "string",
  "work_phone": "string",
  "date_of_birth": "string",
  "occupation": "string",
  "sender_relationship": "string",
  "status": "string",
  "available_payout_methods": [
          "BANK_DEPOSIT",
          "CASH_PICKUP",
          "WALLET",
          "HOME_DELIVERY"
      ]
}

Get recipient by Id

Returns information associated with the provided recipientId for the given senderId.

Note:The recipientId must be of the recipient created under the sender whose id is being provided.

GET /v2/senders/{senderId}/recipients/{recipientId}

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.
recipientId	Yes	UUID	Recipient ID.

Request

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/recipients/{recipientId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "id": "UUID",
  "sender_id": "string",
  "first_name": "string",
  "middle_name": "string",
  "last_name": "string",
  "country": "string",
  "address_line1": "string",
  "address_line2": "string",
  "city": "string",
  "postal_code": "string",
  "province": "string",
  "email": "string",
  "document": "string",
  "home_phone": "string",
  "mobile_phone": "string",
  "work_phone": "string",
  "date_of_birth": "string",
  "occupation": "string",
  "sender_relationship": "string",
  "status": "string",
  "available_payout_methods": [
       "BANK_DEPOSIT",
       "CASH_PICKUP",
       "WALLET",
       "HOME_DELIVERY"
    ]
}

Update Recipient

You can update the recipient details using this API.

Please note that senders shall not be allowed to update the recipient details if a transaction has been previously delivered to that particular recipient.

PUT /v2/senders/{senderId}/recipients/{recipientId}

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.
recipientId	Yes	UUID	Recipient ID.

Request Parameters - Body

Parameter	Required	Type	Description
first_name	Yes	String	The first name of the recipient.
middle_name	No	String	The middle name of the recipient.
last_name	Yes	String	The last name of the recipient.
country	Yes	String	ISO code of the recipient's country
address_line1	Yes	String	Street address of the recipient.
address_line2	No	String	Second line of the street address.
city	Yes	String	Recipient's city.
postal_code	Yes	String	Zip code of the recipient.
province	Yes	String	Name of the state or province.
email	No	Email	The email address of the recipient.
document	No	String
home_phone	No	String	Home phone number.
mobile_phone	No	String	Mobile phone number.
work_phone	No	String	Work phone number.
date_of_birth	No	Date	Date of birth.
occupation	No	String	Occupation.
sender_relationship	Yes	String	Enumerated value Aunt, Brother, Brother in Law, Cousin, Daughter, Father, Father in Law, Friends, Grand Father, Grand Mother, Husband, Mother, Mother in law, Nephew, Niece, Self, Sister, Sister in Law, Son, Uncle, Wife
enable_cash_pickup	No	boolean	Set the flag to true for enabling CASH_PICKUP

Request

curl -X PUT https://sandbox.api.machpay.com/v2/senders/{senderId}/recipients/{recipientId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret' \
  -d { \
    "first_name": "string", \
    "middle_name": "string", \
    "last_name": "string", \
    "country": "string", \
    "address_line1": "string", \
    "address_line2": "string", \
    "city": "string", \
    "postal_code": "string", \
    "province": "string", \
    "email": "string", \
    "document": "string", \
    "home_phone": "string", \
    "mobile_phone": "string", \
    "work_phone": "string", \
    "date_of_birth": "string", \
    "occupation": "string", \
    "enable_cash_pickup": true, \
    "sender_relationship": "string"
  }

Response

{
  "id": "UUID",
  "sender_id": "string",
  "first_name": "string",
  "middle_name": "string",
  "last_name": "string",
  "country": "string",
  "address_line1": "string",
  "address_line2": "string",
  "city": "string",
  "postal_code": "string",
  "province": "string",
  "email": "string",
  "document": "string",
  "home_phone": "string",
  "mobile_phone": "string",
  "work_phone": "string",
  "date_of_birth": "string",
  "occupation": "string",
  "sender_relationship": "string",
  "status": "string",
  "available_payout_methods": [
          "BANK_DEPOSIT",
          "CASH_PICKUP",
          "WALLET",
          "HOME_DELIVERY"
      ]
}

Recipients Account

Recipient Account Object

Name	Type	Description
id	UUID	Recipient Bank ID
recipient_id	UUID	Recipient ID
account_number	string	Account number.
account_type	string	Account type. Enumerated value - savings, checking.
bank_id	integer	Bank ID.
branch_id	integer	Bank Branch ID.
branch_location	string	Bank Branch Address.
identification_value	string	Recipient Wallet ID
identification_type	string	Recipient Wallet type. Enumerated value - TEL
payout_method	string	Payout Method type. Enumerated value - BANK_DEPOSIT, WALLET

Get All Recipient Accounts

This API can be used to fetch all the accounts created under recipient.

GET /v2/senders/{senderId}/recipients/{recipientId}/accounts

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID
recipientId	Yes	UUID	Recipient ID

Request

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/recipients/{recipientId}/accounts \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "result": [
     {
      "id": "string",
      "recipient_id": "string",
      "account_number": "string",
      "account_type": "checking",
      "bank_id": 0,
      "branch_id": 0,
      "branch_location": "string",
      "flagged": false,
      "payout_method": "BANK_DEPOSIT"
    },
    {
       "id": "string",
       "recipient_id": "string",
       "identification_value": "254723993187",
       "identification_type": "TEL",
       "status": "VERIFIED",
       "flagged": false,
       "payout_method": "WALLET"
    }

  ]
}

Add Recipient Account- Bank

This API can be used to add recipient’s bank. Recipient banking information details needs to be added prior to initiating a transfer.

bank_id and bank_branch_id: Obtained From Bank and Branches API

POST /v2/senders/{senderId}/recipients/{recipientId}/accounts

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID
recipientId	Yes	UUID	Recipient ID

Request Parameters - Body

Parameter	Required	Type	Description
account_number	Yes	String	Bank account number.
account_type	Yes	String	Account type. Enumerated value - checking, savings
bank_id	Yes	String	Bank ID.
branch_id	Yes	String	Branch ID.
branch_location	No	String	Branch location.
payout_method	Yes	String	Payout method type. Enumerated value - BANK_DEPOSIT

curl -X POST https://sandbox.api.machpay.com/v2/senders/{senderId}/recipients/{recipientId}/accounts \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret' \
  -d { \
    "account_number": "string", \
    "account_type": "checking", \
    "bank_id": 0, \
    "branch_id": 0, \
    "branch_location": "string",
    "payout_method": "BANK_DEPOSIT"\
  }

Response

{
  "id": "string",
  "recipient_id": "string",
  "account_number": "string",
  "account_type": "checking",
  "bank_id": 0,
  "branch_id": 0,
  "branch_location": "string",
  "flagged": false,
  "payout_method": "BANK_DEPOSIT"
}

Add Recipient Account- Mobile Wallet

This API can be used to add recipient’s mobile wallet.

identification_value : Receiver Mobile wallet ID. Mobile Wallet Id is recipient phone number along with country code and area code.

Mobile Wallet Id	Country Code	Area Code	Receiver Number
254723993187	254	723	993187

POST /v2/senders/{senderId}/recipients/{recipientId}/accounts

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID
recipientId	Yes	UUID	Recipient ID

Request Parameters - Body

Parameter	Required	Type	Description
identification_value	Yes	String	Recipient wallet id.
identification_type	NO	String	Wallet type. Enumerated value - TEL. The default value for identification_type is TEL
payout_method	Yes	String	Payout method type. Enumerated value - WALLET

curl --location --request POST 'https://sandbox.api.machpay.com/v2/senders/{senderId}/recipients/{recipientId}/accounts' \
--header 'X-Client-Id: clientid' \
--header 'X-Client-Secret: clientsecret' \
--header 'Content-Type: application/json' \
--data-raw '{
  "identification_value":"254723993187",
  "identification_type": "TEL",
  "payout_method": "WALLET"
}
'

Response

{
  "id": "string",
  "recipient_id": "string",
  "identification_value": "254723993187",
  "identification_type": "TEL",
  "status": "VERIFIED",
  "flagged": false,
  "payout_method": "WALLET"
}

Get Recipient Account By ID

This API can be used to fetch recipient bank by ID

GET /v2/senders/{senderId}/recipients/{recipientId}/accounts/{accountId}

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID
recipientId	Yes	UUID	Recipient ID
accountId	Yes	UUID	Recipient Account ID

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/recipients/{recipientId}/accounts/{accountId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "id": "string",
  "recipient_id": "string",
  "account_number": "string",
  "account_type": "checking",
  "bank_id": 0,
  "branch_id": 0,
  "branch_location": "string",
  "status": "UNVERIFIED",
  "flagged": false,
  "payout_method": "BANK_DEPOSIT"
}

{
  "id": "string",
  "recipient_id": "string",
  "identification_value": "254723993187",
  "identification_type": "TEL",
  "status": "VERIFIED",
  "flagged": false,
  "payout_method": "WALLET"
}

Transactions

Transaction Object

Name	Type	Description
id	UUID	Transaction ID
reference_number	string	Transaction reference number
sender_id	UUID	Sender ID
sender_funding_account_id	UUID	Sender Funding Account ID
recipient_id	UUID	Recipient ID
recipient_account_id	UUID	Recipient account ID. Receiver account can be recipient bank account or recipient wallet account.
funding_source	String	Enumerated Value: BANK or CARD. It should be based on the sender funding account type.
payer_id	long	Payer ID
payout_method	String	Enumerated Value: CASH_PICKUP or BANK_DEPOSIT or WALLET or HOME_DELIVERY. Payout method for transaction delivery
sender_amount	number	Sender Amount
fee_amount	number	Transaction Fee
exchange_rate	number	Exchange rate used to convert amount.
recipient_amount	number	Amount that is deposited into recipient's bank account.
recipient_currency	string	Currency used in depositing amount.
remittance_purpose	string	Remittance purpose.
note	string	Note.
status	string	Status of the transaction.
delivery_status	string	Delivery status of the transaction.
risk_score	number	Risk score.
ip_address	string	Sender's IP address when the transaction was created.
remarks	string	Remarks
receipt_number	string	MSB reference number of the transaction
payout_reference_number	string	Payout reference number of the cash-pickup transaction
transaction_status_history	list	List of change in status
hold_reasons	list	List of transaction hold reasons

Transaction hold information

Code	Message	Description
T001	Sender Account is not Verified	Transaction is on Hold because, sender KYC status is not verified.
T002	Service not supported in the location	Transaction is on Hold because, GeoIp check did not pass.
T003	Transaction is under review	Transaction is on Hold because, sender risk score was high.

Get the limiting amount for a transaction

This API returns transaction limit of a given sender.

GET /v2/senders/{senderId}/transaction-limit

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.

Request

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/transaction-limit \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "current_tier": "string",
  "sender": {
    "limit": 0
  },
  "receiver": [
    {
      "country": "string",
      "payment_type": "string",
      "limit": 0
    }
  ]
}

Get All Transactions for Sender

This API can be used to fetch the list of all the transactions associated with a particular sender.

GET /v2/senders/{senderId}/transactions

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.

Request

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/transactions \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "results": [
    {
      "id": "string",
      "sender_amount": 0.01,
      "exchange_rate": 0.01,
      "recipient_amount": 0.01,
      "fee_amount": 0,
      "recipient_currency": "string",
      "funding_source": "BANK",
      "sender_id": "string",
      "sender_funding_account_id": "string",
      "recipient_id": "string",
      "payer_id": 1,
      "payout_method": "CASH_PICKUP",
      "note": "string",
      "remittance_purpose": "string",
      "ip_address": "string",
      "status": "string",
      "delivery_status": "string",
      "reference_number": "string",
      "risk_score": 0
    },
    {
      "id": "string",
      "sender_amount": 0.01,
      "exchange_rate": 0.01,
      "recipient_amount": 0.01,
      "fee_amount": 0,
      "recipient_currency": "string",
      "funding_source": "CARD",
      "sender_id": "string",
      "sender_funding_account_id": "string",
      "recipient_id": "string",
      "recipient_account_id": "string",
      "payout_method": "BANK_DEPOSIT",
      "note": "string",
      "remittance_purpose": "string",
      "ip_address": "string",
      "status": "HOLD",
      "delivery_status": "HOLD",
      "reference_number": "string",
      "risk_score": 0,
       "hold_reasons": [
                      {
                          "code": "T002",
                          "message": "Service not supported in the location"
                      }
                  ]
    },
    {
      "id": "string",
      "sender_amount": 0.01,
      "exchange_rate": 0.01,
      "recipient_amount": 0.01,
      "fee_amount": 0,
      "recipient_currency": "string",
      "funding_source": "CARD",
      "sender_id": "string",
      "sender_funding_account_id": "string",
      "recipient_id": "string",
      "recipient_account_id": "string",
      "payout_method": "WALLET",
      "note": "string",
      "remittance_purpose": "string",
      "ip_address": "string",
      "status": "string",
      "delivery_status": "string",
      "reference_number": "string",
      "risk_score": 0
    },
    {
      "id": "string",
      "sender_amount": 0.01,
      "exchange_rate": 0.01,
      "recipient_amount": 0.01,
      "fee_amount": 0,
      "recipient_currency": "string",
      "funding_source": "BANK",
      "sender_id": "string",
      "sender_funding_account_id": "string",
      "recipient_id": "string",
      "payer_id": 2,
      "payout_method": "HOME_DELIVERY",
      "note": "string",
      "remittance_purpose": "string",
      "ip_address": "string",
      "status": "string",
      "delivery_status": "string",
      "reference_number": "string",
      "risk_score": 0
    }

  ]
}

Create Transaction

This API can be used to initiate a transfer. A transaction can be created only after the following criteria are fulfilled.

• Sender's KYC status is other than UNVERIFIED or SUSPENDED.
• At least one sender funding account has been linked by the sender.
• At least one Recipient has been added.

For transactions with funding_source=BANK, a sender funding account with type=BANK must be verified and active. For transactions with funding_source=CARD, a sender funding account with type=CARD must be active.

For transaction amount delivery, the recipient can either receive the amount directly to it's bank account i.e. payout_method=BANK_DEPOSIT, get the amount delivered to the recipient’s address i.e. payout_method = HOME_DELIVERY, or the receiver can pickup the amount from various payout locations i.e. payout_method=CASH_PICKUP.

For payout_method=BANK_DEPOSIT, the recipients bank account information must be added. For payout_method=CASH_PICKUP and payout_method = HOME_DELIVERY, the payer_id must be specified. You can get the list the payers available for the receiver's country through the payers API. For payout_method=WALLET , the recipient wallet account information must be added.

Please use the following values for remittance_purpose:

"Land Purchase", "House Purchase", "House Building", "Loan Repayment", "Education Expense", "Medical Expenses", "Family Expenses", "Savings Deposits", "Marriage Expenses", "Travelling Expenses", "Gifts".

Supports Idempotency Key as part of header to avoid duplicate transaction.

POST senders/{senderId}/transactions

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.

Request Parameters - Body

Parameter	Required	Type	Description
sender_funding_account_id	Yes	UUID	Sender's Funding Account ID.
sender_amount	Yes	number	Amount sender wants to send.
fee_amount	Yes	number	Additional fee.
ip_address	Yes	String	IP address of the sender.
recipient_id	Yes	UUID	Recipient's ID
recipient_account_id	Optional	UUID	Recipient's Account ID. Receiver account can be receiver bank account or receiver wallet account.
funding_source	Optional	String	Enumerated Value: BANK or CARD. It should be based on the sender funding account type. For now, default value =BANK
payer_id	Optional	long	Payer ID. Required if payout_method=CASH_PICKUP or HOME_DELIVERY.
payout_method	Optional	String	Enumerated Value: CASH_PICKUP or BANK_DEPOSIT or WALLET or HOME_DELIVERY. Payout method for transaction amount delivery. For now, default value =BANK_DEPOSIT
exchange_rate	Yes	number	Exchange rate used in transaction.
recipient_amount	Yes	number	Amount that will be debited in recipients's account.
recipient_currency	Yes	String	Recipient's currency.
remittance_purpose	Yes	String	Purpose of remittance.
note	Yes	String	Note.
remarks	Yes	String	Remarks.

Request for transaction with funding_source:CARD and payout_method:BANK_DEPOSIT

curl -X POST https://sandbox.api.machpay.com/v2/senders/{senderId}/transactions \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret' \
  -H 'X-Idempotency-Key: idempotencykey' \
  -d { \
    "sender_amount": 0.01, \
    "exchange_rate": 1.00, \
    "recipient_amount": 0.01, \
    "fee_amount": 0, \
    "recipient_currency": "string", \
    "sender_id": "string", \
    "sender_funding_account_id": "string", \
    "funding_source": "CARD", \
    "recipient_id": "string", \
    "recipient_account_id": "string", \
    "note": "string", \
    "remittance_purpose": "string", \
    "ip_address": "string", \
    "payout_method": "BANK_DEPOSIT" \
  }

Response

{
  "id": "string",
  "sender_amount": 0.01,
  "exchange_rate": 1.00,
  "recipient_amount": 0.01,
  "fee_amount": 0,
  "recipient_currency": "string",
  "sender_id": "string",
  "sender_funding_account_id": "string",
  "funding_source": "CARD",
  "recipient_id": "string",
  "recipient_account_id": "string",
  "note": "string",
  "remittance_purpose": "string",
  "ip_address": "string",
  "status": "string",
  "delivery_status": "string",
  "reference_number": "string",
  "risk_score": 0,
  "payout_method": "BANK_DEPOSIT"
}

Request for transaction with funding_source:BANK and payout_method:CASH_PICKUP

curl -X POST https://sandbox.api.machpay.com/v2/senders/{senderId}/transactions \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret' \
  -H 'X-Idempotency-Key: idempotencykey' \
  -d { \
    "sender_amount": 0.01, \
    "exchange_rate": 1.00, \
    "recipient_amount": 0.01, \
    "fee_amount": 0, \
    "recipient_currency": "string", \
    "sender_id": "string", \
    "sender_funding_account_id": "string", \
    "funding_source": "BANK", \
    "recipient_id": "string", \
    "payer_id": 1, \
    "note": "string", \
    "remittance_purpose": "string", \
    "ip_address": "string", \
    "payout_method": "CASH_PICKUP" \
  }

Response

{
  "id": "string",
  "sender_amount": 0.01,
  "exchange_rate": 1.00,
  "recipient_amount": 0.01,
  "fee_amount": 0,
  "recipient_currency": "string",
  "sender_id": "string",
  "sender_funding_account_id": "string",
  "funding_source": "BANK",
  "recipient_id": "string",
  "payer_id": 1,
  "note": "string",
  "remittance_purpose": "string",
  "ip_address": "string",
  "status": "string",
  "delivery_status": "string",
  "reference_number": "string",
  "risk_score": 0,
  "payout_method": "CASH_PICKUP"
}

Get Transaction by Id

This API can be used to fetch the information associated with a particular transaction specified by transactionId associated with the sender(senderId).

GET /v2/senders/{senderId}/transactions/{transactionId}

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.
transactionId	Yes	UUID	Transaction ID.

Request

curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/transactions \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "id": "string",
  "sender_amount": 0.01,
  "exchange_rate": 1.00,
  "recipient_amount": 0.01,
  "fee_amount": 0,
  "recipient_currency": "string",
  "sender_id": "string",
  "sender_funding_account_id": "string",
  "funding_source": "string",
  "recipient_id": "string",
  "recipient_account_id": "string",
  "note": "string",
  "remittance_purpose": "string",
  "ip_address": "string",
  "status": "string",
  "delivery_status": "string",
  "reference_number": "string",
  "risk_score": 0,
  "receipt_number": "string",
  "payout_method": "BANK_DEPOSIT",
  "status_history": []
}

Cancel Transaction

Cancel transaction.

DELETE /v2/senders/{senderId}/transactions/{transactionId}

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.
transactionId	Yes	UUID	Transaction ID.

Request

curl -X DELETE https://sandbox.api.machpay.com/v2/senders/{senderId}/transactions \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

Body is empty. (204)

Delivery Request

This API is used to request initialization of transaction delivery to recipients. Delivery request can be initiated in the following scenarios:

• Transaction Status is in PENDING or PROCESSED state
• Transaction 'Type' is DEFAULT i.e. No REFUND transaction

PATCH /senders/{senderId}/transactions/delivery-requests/{transactionId}

Request Parameters - URL

Name	Required	Type	Description
senderId	Yes	UUID	Sender ID.
transactionId	Yes	UUID	Transaction ID.

Request Parameters - Body

Parameter	Required	Type	Description
status	Yes	string	Value must be "DELIVERY_REQUESTED".
comment	No	string	Comment.

Request

curl -X PATCH https://sandbox.api.machpay.com/v2/senders/{senderId}/transactions/delivery-requests/{transactionId}\
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret' \
  -d { \
  "status": "DELIVERY_REQUESTED", \
  "comment": "string" \
  }

Response

204

Transaction Invoice API

This API is used to retrieve or download Invoice once a transaction has been successfully created in Machnet system. Please note that the link will only be valid for 60 mins in the sandbox/production environment after which the API needs to be consumed once again for the new link.

Request

URL: https://sandbox.api.machpay.com/v2/senders/{senderId}/transactions/{transactionId}/invoice?type=FILE|LINK
Method: GET

Response

{
  "id": "7bbd2d74-b935-4512-bc8c-303f2d7a129e",
  "file_name": "invoice.pdf",
  "link": "https://bit.ly/2xaQ515",
  "type": "INVOICE"
}

API can be used to either directly download the file or generate a link to the file. The downloaded file will be of Content-Type: application/octet-stream.

Webhooks

When the state of a resource changes, the platform generates a new event resource to record the change. When an Event is created, a Webhook will be created to deliver the Event to any URLs specified by your active Webhook Subscriptions.

Events

Event Name	Event Details	Remarks
sender_created	When a sender has been created in Machnet platform.	This will enable widget feature for sender’s KYC process.
sender_verified	When a sender has been successfully verified through KYC process.
sender_suspended	When a sender is rejected during KYC process.	In this case, you should restrict the customer from initiating the transfer.
sender_review_pending	When a sender KYC process is in review state.	The sender's KYC is being reviewed. No action required from sender.
sender_document_requested	When admin request sender document while processing for sender KYC.	The sender needs to either re-upload their document or provide additional document(via KYC widget) as requested by admin.
sender_kyc_retry_requested	When admin request sender to review sender information for sender KYC.	The sender needs to either edit their current information or provide additional information(via KYC widget) as requested by admin.
sender_verification_documentation_failed	When the document supplied by the sender has been rejected.
sender_reverification_needed	When the details entered by the sender does not satisfy verification check.	Sender needs to reverify(re-edit) their details to ensure there is no mistake in the data and submit the request once again.
sender_verification_documentation_needed	When the sender needs to supply new document.	In this case, the sender will have to upload/re-upload a valid document.
sender_verification_documentation_approved	When the document supplied by the sender has been verified.
transaction_initiated	When transaction has been initiated by the sender.	The user transaction will go through GeoIP, Fraud and Balance check during this process.
transaction_created	When transaction has been successfully created in Machnet platform.	Once the transaction has passed the GeoIP, Fraud and Balance check.
transaction_processed	When the funds have been successfully debited from the sender's funding account.
transaction_failed	When the funds cannot be debited from the sender's funding account. This usually occurs due to failure such as insufficient funds, fraudulent details etc.
transaction_canceled	When transaction has been canceled either by the customer or admin.
transaction_returned	When transaction has been returned.
transaction_refunded	When the funds have been credited back to the sender's funding account.
transaction_completed	When the funds have been successfully debited from the sender's funding account and credited to beneficiary’s bank account.
transaction_onhold	When the sender's transaction on hold. The hold reason is provided in the response when fetching transaction information.	This event requires admin intervention and will either be cancelled or moved to Pending state.
bank_added	When the sender's bank account has been successfully added.	This will enable bank account to RECEIVE amount.
bank_removed	When the sender's bank account has been removed.
sender_bank_login_required	When the sender needs to update their bank credentials.
card_added	When the sender's card account has been successfully added.	This will enable sender to make transactions through the associated card.
card_removed	When the sender's card account has been removed.
exchangerate_approved	When the requested exchange rate has been approved.
exchangerate_disapproved	When the requested exchange rate has been disapproved.
fee_approved	When the fee change has been approved.
tier_approved	When the requested tier upgrade has been approved.
tier_disapproved	When the requested tier upgrade has been disapproved.
transaction_delivery_pending	When the transaction has been successfully created and can be forwarded for delivery.
transaction_delivery_requested	When the delivery of transaction to the beneficiary has been initiated.
transaction_delivery_onhold	When the transaction delivery has been moved to hold state.	This is usually due to MSB/Delivery Partner blocking the transaction delivery process.
transaction_delivery_failed	When the delivery of transaction has failed.
transaction_delivered	When the funds have been successfully delivered to the recipient.

Webhooks Integration

After the Subscription API has been setup the webhooks is ready to use. Webhooks will be fired when any event listed is triggered from our end. We will trigger a POST request to the URL provided on the Subscription API.

Webhooks Request

When an event is created on our end we POST following details as part of the webhook to the URL mentioned on Subscription API.

HEADER x-raas-webhook-signature : d2b730bba0de481fb079fff1478435231a9b410005ee599e67428930b7f340c3 x-raas-event : transaction_completed POST PAYLOAD

{
  "id": "82646f2c-447a-4214-a6ad-7d43e87d7fc4",
  "resource_id": "dab8da2c-61ea-42cf-a7c5-223967bebb81",
  "sender_id": "ee3aa0ac-8d18-4a7b-adaf-c5cc8a8db62f",
  "event_name": "transaction_completed",
  "subscription_id": "caec6725-bf0a-4ca4-9f8c-153f4da87259",
  "event_id": "cf8ae9f3-dc8b-4317-8307-a0d71294e9a7",
  "timestamp": "2017-07-02T22:88:12.120Z"
}

DETAILS

Parameter	Description
x-raas-webhook-signature	We generate a signature using the secret mentioned on Subscription API.
x-raas-event	Event Name
id	Webhook unique identifier
event_name	Event name. Same as that of header x-raas-event
resource_id	Id of resource for which the event was generated. If transaction_completed is triggered the resource_id will be transaction id.You can fetch the particular resource using the resource_id.
sender_id	If sender related resources are triggered as part of event then sender_id will be sent as part of the payload.
event_id	Event Id.
subscription_id	Subscription Id for which this event was generated.

Securing Webhooks

We allow you to set secret as part of the Subscription API. Secret used on Subscription API will be used to create hash which will be sent as part of the webhooks request i.e. x-raas-webhook-signature and is a SHA256 HMAC hash of the request body with the key being your webhooks secret. You can validate the webhooks request by generating the same SHA256 HMAC hash and comparing it to the x-raas-webhook-signature sent with the payload. NOTE: This step is optional but we highly recommend you to do so.

Responding to Webhooks

When you receive the webhooks events, you can respond back with following HTTP Status after the processing has been completed on your end.

HTTP Status	Description
2xx HTTP	This will acknowledge that the webhooks event was successfully captured and no further webhooks event will be generated from our end.
409 Conflict	If this HTTP code is returned from your end, we will trigger the webhooks on fixed interval until a success response is received from your end.
Rest of HTTP Codes	Any other response during webhooks response including 3xx codes will be marked as failure. Consecutive Webhooks Failures will pause the subscriptions for which the webhooks failed. You will have to update the paused subscriptions if you want to receive further webhooks on that subscription.

Retry Case

If a webhooks is not successfully received for any reason, we will continue trying to send the webhooks 10 more times every hour.

Duplicate Events

Subscriptions endpoints may occasionally receive the same event more than once. We advise you to properly handle such cases on your end.

Webhook Subscriptions

Create a webhook subscription to receive POST requests from the platform (called webhooks) when events associated with your application occur. Webhooks are sent to a URL which you provide when creating a webhook subscription. Refer to the events section for the list of events that trigger webhooks.

Subscription Object

Name	Type	Description
id	UUID	ID
end_point	URL	URL where webhooks will be forwarded.
secret	string	A key used to maintain message integrity.
active_from	datetime	Date/time when the subscription URL was created.
expired_at	datetime	Date/time when the subscription URL was removed.
is_paused	boolean	True if the subscription is paused.
is_active	boolean	True if the subscription is active.

List Registered Webhooks

GET /v2/subscriptions

Request

curl -X GET https://sandbox.api.machpay.com/v2/subscriptions \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Response

{
  "results": [
    {
      "id": "string",
      "end_point": "string",
      "secret": "string",
      "active_from": "2019-07-04T04:45:05.125Z",
      "expired_at": "2019-07-04T04:45:05.126Z",
      "is_paused": true,
      "is_active": true
    }
  ]
}

Subscribe

POST /v2/subscriptions

Request Parameters - Body

Parameter	Required	Type	Description
end_point	Yes	URL	Subscription URL.
secret	Yes	secret	String used to hash the message.

Request

curl -X POST https://sandbox.api.machpay.com/v2/subscriptions \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret' \
  -d { \
      "end_point": "string", \
      "secret": "string" \
  }

Response

{
  "id": "uuid",
  "end_point": "string",
  "secret": "string",
  "active_from": "2019-07-04T04:45:05.125Z",
  "expired_at": "2019-07-04T04:45:05.126Z",
  "is_paused": false,
  "is_active": true
}

Pause Subscription

POST /v2/subscriptions/{subscriptionId}

Request Parameters - URL

Name	Required	Type	Description
subscriptionId	Yes	UUID	Subscription ID.

Request Parameters - Body

Parameter	Required	Type	Description
pause	Yes	boolean	Set to true if subscription is to be paused.

Request

curl -X POST https://sandbox.api.machpay.com/v2/subscriptions/{subscriptionId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret' \
  -d { \
      "pause": true \
  }

Response

{
  "id": "string",
  "end_point": "string",
  "secret": "string",
  "active_from": "2019-07-04T04:45:05.125Z",
  "expired_at": "2019-07-04T04:45:05.126Z",
  "is_paused": false,
  "is_active": true
}

Remove Subscription

DELETE /v2/subscriptions/{subscriptionId}

Request Parameters - URL

Name	Required	Type	Description
subscriptionId	Yes	UUID	Subscription ID.

Request

curl -X DELETE https://sandbox.api.machpay.com/v2/subscriptions/{subscriptionId} \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'

Test values for Sandbox

The Sandbox environment allows you to test the Machnet’s Platform without any real-world impact. No real personal/ financial data is used and Machnet provides a way to simulate various test cases by utilizing dummy data in the Sandbox environment.

Test Value for GeoFencing

In order to adhere to the compliance requirement, our service uses GeoFencing to restrict users from completing their KYC or creating transaction from the state they have signed up from. In order to successfully submit a KYC request or to create a transaction in the sandbox environment, please ensure that the IP address you are passing corresponds to the state of origination. If a transaction is created from a state that is not licensed under the MSB (under which the user has signed up), the transaction will be automatically cancelled or in case of KYC, the request will not be submitted. You can pass the following values through the XFF HTTP header to simulate the state of origination.

IP Address

Corresponding States

10.10.*.<X> E.g. 10.10.22.11 will simulate the state of Georgia

‘X’: ‘corresponding status’ '1': ['AL'], '2': ['AK'], '3': ['AZ'], '4': ['AR'], '5': ['CA'], '6': ['CO'], '7': ['CT'], '8': ['DE'], '9': ['DC'], '10': ['FL'], '11': ['GA'], '12': ['HI'], '13': ['ID'], '14': ['IL'], '15': ['IN'], '16': ['IA'], '17': ['KS'], '18': ['KY'], '19': ['LA'], '20': ['ME'], '21': ['MD'], '22': ['MA'], '23': ['MI'], '24': ['MN'], '25': ['MS'], '26': ['MO'], '27': ['MT'], '28': ['NE'], '29': ['NV'], '30': ['NH'], '31': ['NJ'], '32': ['NM'], '33': ['NY'], '34': ['NC'], '35': ['ND'], '36': ['OH'], '37': ['OK'], '38': ['OR'], '39': ['PA'], '40': ['RI'], '41': ['SC'], '42': ['SD'], '43': ['TN'], '44': ['TX'], '45': ['UT'], '46': ['VT'], '47': ['VA'], '48': ['WA'], '49': ['WV'], '50': ['WI'], '51': ['WY']

Test values for Customer Verification / KYC Status

Various customer verification statuses can be simulated in Sandbox by supplying specific values in the First Name field. You can use the values provided in the following table to simulate the corresponding KYC status.

First Name	Customer Verification Status	Description
Retry	Retry Case	The customer would be taken to the review screen whereby they will need to make the necessary amendments and submit their request once again.
Verified	Verified Customer Record	The customer status would be verified.
Suspended	Suspended Case	The customer status would be suspended. In production, the client will need to contact Machnet for the suspended case.
Any other value	Retry/Suspended	The customer status will first be Retry and after the next submission, it will be suspended.

Note:

• If 4 digit SSN is asked, use the above details and 3333 for SSN
• If 9 digit SSN is asked, use the above details and 112223333 for SSN

Test value for Document Verification

Provide the following guidelines to customers to assist them with taking the highest quality image possible: 1. Capture document images with at least a 5 MP camera. 2. Place the document on a dark background that contrasts with their document. 3. Ensure that the dark background fills about 10% of the top, bottom, left, and right sides of the image. 4. Confirm that all four corners of the document are clearly visible in the image. 5. The image should be in sharp focus, not rotated or skewed, and taken in a well-lit room on a camera without flash enabled. 6. The image needs to be less than 5MB in Size and should be in either .jpg or .jpeg format.

Image for Document Verification

You can upload this image for successful document verification.

Image for Document Verification Failure

Using document other than the one provided for successful verification will simulate the failure case of document verification.

Image for Bad Image Detection

In case a user does not submit an image based on the prescribed specification e.g. Blurry, Four Corners not visible etc., they will be allowed to submit an image 2 more times. To simulate Bad Image detection you can use this image.

Test Values for Sender Bank

Test Value for linking a Bank account

Username	Password	MFA	Case
user_good	pass_good	-	Every account linked will have same details.
user_good	mfa_device	1234	MFA Required
user_custom	{}	-	Every account linked will have random details.

Test value for Balance Check

If a user’s bank account does not have sufficient funds at the time of transaction creation, the transaction will be automatically cancelled.

When adding a funding source an account with balance can be linked. Enter amount lower than the one available in the linked funding source for Balance check Pass. Enter amount higher than the one available in the linked funding source for Balance check Fail.

Test value for Debit Card

-Note: To be used in Card Widget

Network	Type	Card Number	Status
Star	Exempted	9010110999999994	Card Successfully Added
Start	Regulated	9011110999999993	Card Successfully Added
Pulse	Exempted	9020110999999992	Card Successfully Added
Pulse	Regulated	9021110999999991	Card Successfully Added
NYCE	Exempted	9030110999999990	Card Successfully Added
NYCE	Regulated	9031110999999999	Card Successfully Added
Accel	Exempted	9080110999999999	Card Successfully Added
Accel	Regulated	9081110999999998	Card Successfully Added
Visa	Exempted	9400110999999992	Card Successfully Added
Visa	Regulated	9401110999999991	Card Successfully Added
MasterCard	Exempted	9501110999999990	Card Successfully Added
MasterCard	Regulated	9500110999999991	Card Successfully Added
Star	Credit Card	9010210999999992	Card Not Supported
Star	Debit Card	9010101999999993	Pull Transaction Not Supported

Security (CVV) Code	123
Expiry Date	Any future date will work

Test value for Transaction Status Change

For Bank Deposit

Transaction Amount	Status
All values except below mentioned	Processed
99 (Including Fee)	Failed
55 (Including Fee)	Returned

For Debit Card transaction

Transaction Amount	Status
30	Processed
300	Cancelled

Test value for Transaction Risk Score Check

The risk score of every transaction created in Machnet Platform is evaluated and necessary action is taken, which can result in a transaction being canceled or kept on hold for further checks. The risk score can lead to the following scenarios:

1. If a transaction has a Risk Score between 1-7, the transaction will pass the Risk Check
2. If a transaction has a Risk Score between 7-70, the transaction will go On Hold and the transaction must be approved or canceled from the compliance team.
3. If a transaction has a Risk Score higher than 70, the transaction will be automatically canceled.

To simulate the various risk-score of a transaction, you can use the following test values.

Sender Email	Min Risk Score	Max Risk Score	Remarks
All values except below mentioned	1	7
<>suspicious<>@example.com	7	70	You need to include the word suspicious in the sender email to get a risk score between 7 and 70.
<>risky<>@example.com	70	100	You need to include the word risky in the sender email to get a risk score greater than 70.

Changelog

Version 1.6

February 19, 2021

• Remove Deprecated API as receiver bank.
• Add method to add receiver account.

Version 1.5

October 01, 2020

• Add home delivery as payout.

Version 1.4

September 15, 2020

• Add receiver account section.
• Deprecate receiver bank.

Version 1.3

October 10, 2019

• Rearrange transaction invoice api and widget token generation part.

Version 1.2

August 27, 2019

• Make changes to the description text to the API methods.

Version 1.1

July 24, 2019

• Update response body and test values

Version 1.0

July 5, 2019

• Initial draft