NAV
Shell HTTP JavaScript Ruby Python

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

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 v1.0 Setup

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

  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, 3ds
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

  1. 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.
BANK_EXIT bank Sender's Bank has been exited.
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.
THREE_DS_VERIFIED 3ds 3DS verification Successful.
THREE_DS_HOLD 3ds 3DS verification is hold.
THREE_DS_FAILED 3ds 3DS verification Unsuccessful.
THREE_DS_IN_PROGRESS 3ds 3DS verification is in progress.

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.

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.

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.

3DS Widget

This widget will be accessible after card txn is created on Machnet platform. This widget can be triggered by passing widget type as 3ds. In this case, the widget needs to be initialized using the senderId, token and 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>

Widget v2.0 Setup

It is required to use widget v2.0 to provide the KYC information which are sensitive and cannot be updated via KYC API. You need to follow the steps mentioned below to setup the widget v2.0.

  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",
    width: "100%",
    height: "200px",
    type: "kyc",
    locale: "en",
    version: '2.0',
    fields: 'senderIdInfo|senderFullSSN',
    stylesheet: "https://example.com/mystyle.css",
    senderId: "62018cb0-e183-4a72-a691-844c213a693a",
    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.
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
Widget v2.0 supports kyc widget type only.
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.
version Yes String 1.0 is the default value. To use version 2.0 please include the version number in the script.
fields Yes String The kyc fields provided will be rendered by the widget. To render multiple fields, fields will be concatenated and delimited by a pipe '|' character.

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 Parameters - Query String

Parameter Required Type Description
countryCode No String ISO Code of a Country
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"
      }
    }
  ]
}
Request with filter params
curl --location --request GET https://sandbox.api.machpay.com/v2/countries/?countryCode=KEN' \
-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 the 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
countryCode No String ISO Code of a Country
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
    }
  ]
}
Request with filter params
curl -X GET https://sandbox.api.machpay.com/v2/states?countryCode=KEN \
  -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
    }
  ]
}

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.
receiving_currency List List of 3-character ISO code of the currency supported by the bank.
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
countryCode No String ISO Code of a Country
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"
    }
  ]
}
Request with filter params
curl -X GET https://sandbox.api.machpay.com/v2/banks?countryCode=KEN \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: clientid' \
  -H 'X-Client-Secret: clientsecret'
Response
{
  "id": 00,
  "name": "Test Bank",
  "country": "KEN",
  "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",
  "receiving_currency" : ["NGN", "USD"],
  "branches": [
    {
      "id": 20,
      "name": "Test Bank Branch"
    }
  ]
}

Payers

Payers are the entities that delivers the transaction amount to receiver in receiver's country. A payer is associated with the destination country and supports one of the following delivery methods:

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 when the delivery_method is CASH_PICKUP or HOME_DELIVERY.

The payer id is also required when adding receiver wallet account. It links receiver wallet account with wallet payer.

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"
        },
        {
            "id": 2,
            "name": "Acme ",
            "country": "ARM",
            "website": "",
            "delivery_method": "HOME_DELIVERY"
        },
        {
            "id": 3,
            "name": "Acme",
            "country": "KEN",
            "website": "",
            "delivery_method": "WALLET"
        }
    ],
    "paging": {
        "total_count": 3
    }
}

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": "Payer Address",
    "phone_number": "+123 456789",
    "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.
nationality string Sender’s nationality. Provide 3-letter ISO code of the country.
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.
nationality No string Sender’s nationality. Provide 3-letter ISO code of the country.
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", \
      "nationality": "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",
  "nationality": "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",
  "nationality": "string",
  "mobile_phone": "string",
  "requested_fields": [
          "SENDER_SOURCE_OF_FUND"
      ],
  "cip_failure_reasons": [
          "No public record found"
      ]
}

Sender KYC

You can perform KYC of a sender using either the widget v1.0 or API. The sender information can be sent through API except for sensitive information such as sender SSN and sender identification document. To provide sensitive information you can use widget v2.0. For more information please refer to the widget v2.0 section.

Get KYC Fields

This provides the current KYC status of sender and the list of KYC fields which represents sender information required for KYC in current tier level. You should fetch the KYC fields and update the sender information as required by the tier level.

KYC field Description
senderFullName Sender full name.
It includes First Name, Middle Name and Last Name
senderEmail Sender email address
senderGender Sender gender
senderDOB Sender date of birth.
It includes Year, Month and Day
senderPhone Sender phone number
senderAddress Sender Address.
It includes AddressLine1, AddressLine2, City, State and Zipcode
senderNationality Sender’s nationality
senderFourDigitSSN Sender four digit SSN. Sender four digit SSN should be provided via widget v2.0
senderFullSSN Sender full nine digit SSN. Sender full SSN should be provided via widget v2.0
senderIdInfo Sender identification document. Sender identification document should be provided via widget v2.0
senderCompanyDetails Sender company details.
It includes Company Name, Company Address, Company Phone Number
senderOccupation Sender occupation details.
senderProofOfAddress Document that specifies sender current address.
Types of sender proof of address document : Utility Bill, Bank or Credit Card Statement, Driver License, Council Tax Bill,Vehicle Registration or Tax and Lease Agreement
senderSourceOfFund Document that specifies sender source of fund.
Types of sender source of fund document : Bank Statement and Pay Slip
senderRemitAgreement Sender remit agreement. The sender remit agreement value should be always true for KYC process
URL

GET /v2/senders/{senderId}/kyc-fields

Request Parameters

Name Required Type Description
senderId Yes UUID Sender ID
Request
 curl -X GET https://sandbox.api.machpay.com/v2/senders/{senderId}/kyc-fields \
   -H 'Accept: application/json' \
   -H 'X-Client-Id: clientid' \
   -H 'X-Client-Secret: clientsecret'
Response
   {
       "sender_id" : "sender_UUID",
       "kyc_status" : "KYC_STATUS",
       "metadata" : [
           {
               "level" : "LEVEL1",
               "fields" : [
                   "senderDOB",
                   "senderFourDigitSSN",
                   "senderPhone",
                   "senderEmail",
                   "senderAddress",
                   "senderRemitAgreement",
                   "senderFullName",
                   "senderGender",
                   "senderNationality"
               ]
           }
       ]
   }

GET KYC information

The API enables you to retrieve the sender KYC information from the system.

URL

GET /v2/senders/{senderId}/kyc-info

Request Parameters
Name Required Type Description
senderId Yes UUID Sender ID
Request
curl --location --request GET 'https://sandbox.api.machpay.com/v2/senders/{senderId}/kyc-info' \
--header 'X-Client-Id: clientId' \
--header 'X-Client-Secret: clinetSecret' \
--header 'Content-Type: application/json' \
Response Body
Name Type Description
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
gender String Gender of the sender
email String The email address of the sender.
mobile_phone String 10-15 digit mobile phone number of sender
date_of_birth String Sender date of birth (yyyy-mm-dd)
address_line1 String Sender address line 1
address_line2 String Sender address line 2
state String 2-letter ISO code of the sender's state
city String Sender's city
zipcode String Sender's postal code
nationality String Sender’s nationality. 3-letter ISO code of the country.
kyc_status Enum KYC status of sender.
UNVERIFIED,IN_PROGRESS, REVIEW_PENDING, RETRY, VERIFIED, RETRY_REQUESTED,DOCUMENT_REQUESTED,SUSPENDED,DOCUMENT
document_status Enum Document status of sender.
APPROVED, RETRY, PENDING, FAILED, MANUAL_VERIFICATION_REQUIRED, NONE,MANUALLY_VERIFIED,CANCELED
sender_company Object Sender company details
       occupation String Sender's occupation
       company_name String Sender's company name
       company_address String Address of sender's company
       company_phone String Phone number of sender's company
Response
{
    "id": "senderId",
    "first_name": "John",
    "middle_name": "",
    "last_name": "Doe",
    "email": "user@sandbox.com",
    "gender": "female",
    "mobile_phone": "1234567890",
    "date_of_birth": "1974-06-17",
    "address_line1": "123 California Avenue",
    "city": "Santa Monica",
    "state": "CA",
    "country": "USA",
    "zipcode": "90403",
    "nationality": "ARM",
    "sender_company": {
        "occupation": "Engineer"
    },
    "kyc_status": "DOCUMENT_REQUESTED",
    "document_status": "NONE",
    "user_agreement": true
}

Update KYC Information

The API allows you to update the sender information. You can provide all the required sender information at once. You can also update the sender information partially by using this API multiple times as required.

URL

PATCH /v2/senders/{senderId}/kyc-info

Request Parameters
Name Required Type Description
senderId Yes UUID Sender ID
Request Body
Name Type Description
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
gender String Gender of the sender
email String The email address of the sender.
mobile_phone String 10-15 digit mobile phone number of sender
date_of_birth String Sender date of birth (yyyy-mm-dd)
address_line1 String Sender address line 1
address_line2 String Sender address line 2
state String 2-letter ISO code of the sender's state
city String Sender's city
zipcode String zipcode
nationality string Sender’s nationality. Provide 3-letter ISO code of the country.
sender_company Object Sender company details
       occupation String Sender's occupation
       company_name String Sender's company name
       company_address String Address of sender's company
       company_phone String Phone number of sender's company
Request
 curl --location --request PATCH 'https://sandbox.api.machpay.com/v2/senders/{senderId}/kyc-info' \
--header 'Content-Type: application/json' \
--header 'X-Client-Id: clientid ' \
--header 'X-Client-Secret: clientSecret ' \
--data-raw '{
             "first_name": "John",
             "middle_name" : "",
             "last_name": "Doe",
             "mobile_phone": "1234567890",
             "email": "user@sandbox.com",
             "gender": "male",
             "date_of_birth": "1974-06-17",
             "address_line1": "123 California Avenue",
             "address_line2": "",
             "city": "Santa Monica",
             "state" : "CA",
             "zipcode": "90403",
             "nationality": "ARM",
             "user_agreement" : true,
             "sender_company": {
                     "occupation": "Engineer"
                 }
             }'
Response Body
Name Type Description
id UUID Id of the sender
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
gender String Gender of the sender
email String The email address of the sender.
mobile_phone String 10-15 digit mobile phone number of sender
date_of_birth String 2-letter ISO code of the sender's state
address_line1 String Sender address line 1
address_line2 String Sender address line 2
state String 2-letter ISO code of the sender's state
nationality string Sender’s nationality. 3-letter ISO code of the country.
city String Sender's city
zipcode String zipcode
kyc_status Enum KYC status of sender.
UNVERIFIED,IN_PROGRESS, REVIEW_PENDING, RETRY, VERIFIED, RETRY_REQUESTED,DOCUMENT_REQUESTED,SUSPENDED,DOCUMENT
sender_company Object Sender company details
       occupation String Sender's occupation
       company_name String Sender's company name
       company_address String Address of sender's company
       company_phone String Phone number of sender's company
Response
  {
      "id": "senderId",
      "first_name": "John",
      "middle_name" : "Mid",
      "last_name": "Doe",
      "mobile_phone": "1234567890",
      "email": "user@sandbox.com",
      "gender": "male",
      "date_of_birth": "1974-06-17",
      "address_line1": "123 California Avenue",
      "address_line2": "",
      "city": "Santa Monica",
      "state" : "CA",
      "zipcode": "90403",
      "nationality": "ARM",
      "kyc_status": "UNVERIFIED",
      "user_agreement": true
   }

Initiate Sender KYC

The API enables you to initiate the sender's KYC process. It is required to provide all the required information before initiating sender's KYC.

Note: If the API is called with insufficient information, it results in error response.

{
    "status": 400,
    "code": "BAD_REQUEST",
    "message": "Some fields are missing for [SENDER_GENDER]"
}
URL

PUT /v2/senders/{senderId}/initiate-kyc

Request Parameters
Name Required Type Description
senderId Yes UUID Sender ID
Request
 curl --location --request PUT 'https://sandbox.api.machpay.com/v2/senders/{senderId}/initiate-kyc' \
--header 'Content-Type: application/json' \
--header 'X-Client-Id: clientid ' \
--header 'X-Client-Secret: clientSecret ' \
Response Body
Name Type Description
sender_id UUID Id of the sender
kyc_status Enum Updated KYC status of sender.
UNVERIFIED,IN_PROGRESS, REVIEW_PENDING, RETRY, VERIFIED, RETRY_REQUESTED,DOCUMENT_REQUESTED,SUSPENDED,DOCUMENT
document_status Enum Document status of sender.
APPROVED, RETRY, PENDING, FAILED, MANUAL_VERIFICATION_REQUIRED, NONE,MANUALLY_VERIFIED,CANCELED
Response
  {
      "senderId": "senderId",
      "kycStatus": "IN_PROGRESS",
      "documentStatus": "PENDING"
  }

If KYC status is RETRY, you should prompt sender to provide additional information. The additional information required for KYC can be retrieved from Get KYC Fields API.

If KYC status is REVIEW_PENDING, the admin user can request sender for additional information such as senderFullSSN,senderProofOfAddress, and senderSourceOfFund from dashboard. The additional information requested by admin user can be retrieved from Get KYC Fields API.

Note: If the additional information required includes sender SSN or sender identification document, sender information should be provided via widget v2.0. For more information please refer to the widget section.

Request
curl --location --request GET 'https://baseURL/v2/senders/{senderId}/kyc-fields' \
--header 'X-Client-Id: clientId ' \
--header 'X-Client-Secret: clientSecret' \
--header 'Content-Type: application/json' \
Response
{
    "sender_id": "sender_id",
    "kyc_status": "RETRY",
    "metadata": {
        "level": "LEVEL1",
        "fields": [
            "senderFourDigitSSN"
        ]
    }
}

{
    "sender_id": "sender_id",
    "kyc_status": "REVIEW_PENDING",
    "metadata": {
        "level": "LEVEL1",
        "fields": [
            "senderProofOfAddress"
        ]
    }
}

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

Guide for Bank Authentication

Click here for Oauth Bank Authentication

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
avs_code string AVS Response Code of the Card. For Reference: AVS Code for 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",
    "avs_code": "Y"
}

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",
      "avs_code": "Y"
    }
  ]
}

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 Recipient's date of birth (yyyy-mm-dd).
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 Recipient's date of birth (yyyy-mm-dd).
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 Recipient's date of birth (yyyy-mm-dd).
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
status string Account Status. Enumerated value - VERIFIED, UNVERIFIED
payer_id integer Id of payer associated with receiver wallet.
account_holder_name.first_name String The account holder’s first name. When applicable, the provided account holder name is matched with the actual account holder’s name received from the bank/wallet provider for verification purposes. If this field is not provided, the first name of the recipient will be used.
account_holder_name.middle_name String The account holder’s middle name. If this field is not provided, the middle name of the recipient will be used.
account_holder_name.last_name String The account holder’s last name. If this field is not provided, the last name of the recipient will be used.

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",
      "status": "UNVERIFIED",
      "account_holder_name": {
        "first_name": "string",
        "middle_name": "string",
        "last_name": "string"
      },
    },
    {
       "id": "string",
       "recipient_id": "string",
       "identification_value": "254723993187",
       "identification_type": "TEL",
       "status": "VERIFIED",
       "flagged": false,
       "payout_method": "WALLET",
       "account_holder_name": {
        "first_name": "string",
        "middle_name": "string",
        "last_name": "string"
      },
    }

  ]
}

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
account_holder_name.first_name No String The bank account holder’s first name. If this field is not provided, the first name of the recipient will be used.
account_holder_name.middle_name No String The bank account holder’s middle name. If this field is not provided, the middle name of the recipient will be used.
account_holder_name.last_name No String The bank account holder’s last name. If this field is not provided, the last name of the recipient will be used. 
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", \
    "account_holder_name": {
        "first_name": "string",
        "middle_name": "string",
        "last_name": "string"
    }
  }

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",
  "status": "UNVERIFIED",
  "account_holder_name": {
      "first_name": "string",
      "middle_name": "string",
      "last_name": "string"
  }
}

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
payer_id Yes Integer Id of payer associated with receiver wallet
account_holder_name.first_name No String The wallet account holder’s first name. When applicable, the provided account holder name is matched with the actual account holder’s name received from the wallet provider for verification purposes. If this field is not provided, the first name of the recipient will be used.
account_holder_name.middle_name No String The wallet account holder’s middle name. If this field is not provided, the middle name of the recipient will be used.
account_holder_name.last_name No String The wallet account holder’s last name. If this field is not provided, the last name of the recipient will be used. 
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",
  "payer_id": 3,
  "account_holder_name": {
      "first_name": "string",
      "middle_name": "string",
      "last_name": "string"
  }
}
'

Response

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

Get Wallet Information

This API is used to get information about wallet account holder.

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

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

Response

Parameter Type Description
recipient_id UUID Recipient Id
payout_method String Payout Method
payload Object Payload

Payload

Parameter Type Description
status String AVAILABLE, UNAVAILABLE, UNREGISTER, SERVICE_NOT_PRESENT
full_name String Full name of the account holder
identifier String Wallet identification number 
curl --location --request POST 'https://sandbox.api.machpay.com/v2/senders/{senderId}/recipients/{recipientId}/accounts/information' \
--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

{
    "recipient_id": "string",
    "payout_method": "WALLET",
    "payload": {
        "status": "AVAILABLE",
        "full_name": "JOSEPH MBUGUA NJEHU",
        "identifier": "254723993187"
    }
}

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",
  "account_holder_name": {
      "first_name": "string",
      "middle_name": "string",
      "last_name": "string"
  }
}

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

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. Enumerated Value: INITIATED, PENDING, HOLD, PROCESSED, CANCELED, REFUNDED, RETURNED, FAILED
delivery_status string Delivery status of the transaction. Enumerated Value: PENDING, HOLD, DELIVERY_PAYOUT_READY, DELIVERY_FAILED, DELIVERY_REQUESTED, DELIVERED, DELIVERY_AUTHORIZED
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
bonus_amount number Bonus amount accommodated by affiliate
three_ds.enabled Boolean Represents if the 3DS service is configured or not.
three_ds.status String 3DS status of the card transaction. Enumerated value UNVERIFIED, IN_PROGRESS, HOLD, VERIFIED, FAILED.

Transaction hold information

Code Message Description
T001 Sender Account is not Verified Sender KYC is not verified. Transactions can only be processed for verified users.
T002 Service not supported in the location Transaction was created using an IP outside of the permitted region.
T003 Transaction is under review Transaction may be risky and is under review by compliance.
T004 Receiver account is not verified Receiver’s account is not verified. Please contact customer support.
T005 Bank Credentials need to be updated by Sender User’s bank credentials need to be updated. Please ask the user to re-login to their bank account.
T007 Unable to conduct balance check Balance of the user’s funding source could not be checked. This increases chances of NSF. Please contact customer support.
T008 Transaction under review Transaction is under compliance review. Please contact customer support.
T009 Unable to conduct compliance checks Required compliance checks could not be conducted. Please contact customer support.
T0010 Unable to conduct compliance checks Required compliance checks could not be conducted. Please contact customer support.
T0011 Connection issue We are facing connection issues. Please contact customer support.
T0012 Connection issue We are facing connection issues. Please contact customer support.
T0013 Connection issue We are facing connection issues. Please contact customer support.
T0014 Connection issue We are facing connection issues. Please contact customer support.
T0015 Connection issue We are facing connection issues. Please contact customer support.
T0016 Connection issue We are facing connection issues. Please contact customer support.
T0017 Sender under compliance review. User is under compliance review. Please contact customer support.
T0018 Unable to conduct card verification. Card verification of the user could not be completed. Please contact customer support.
R001 Transaction under review Transaction is under compliance review. Please contact customer support.
R002 Transaction under review Transaction is under compliance review. Please contact customer support.
R003 Transaction under review Transaction is under compliance review. Please contact customer support.

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.11,
      "exchange_rate": 0.1111,
      "recipient_amount": 0.01,
      "fee_amount": 0,
      "bonus_amount": 0.00,
      "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",
      "payout_reference_number" : "string",
      "risk_score": 0
    },
    {
      "id": "string",
      "sender_amount": 0.11,
      "exchange_rate": 0.1111,
      "recipient_amount": 0.01,
      "fee_amount": 0,
      "bonus_amount": 0.00,
      "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,
      "three_ds": {
        "enabled": true,
        "status": "VERIFIED"
      },
      "hold_reasons": [
                        {
                          "code": "T002",
                          "message": "Service not supported in the location"
                        }
                      ]
    },
    {
      "id": "string",
      "sender_amount": 0.11,
      "exchange_rate": 0.1111,
      "recipient_amount": 0.01,
      "fee_amount": 0,
      "bonus_amount": 0.00,
      "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,
      "three_ds": {
        "enabled": true,
        "status": "string"
      },
    },
    {
      "id": "string",
      "sender_amount": 0.11,
      "exchange_rate": 0.1111,
      "recipient_amount": 0.01,
      "fee_amount": 0,
      "bonus_amount": 0.00,
      "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.

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.
bonus_amount Optional number Bonus amount accommodated by affiliate
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. Accepts upto 4 decimal digits.
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.
three_ds.enabled Yes [incase of CARD] Boolean Represents if the 3DS service is configured or not.
three_ds.status No String 3DS status of the card transaction. Enumerated value UNVERIFIED, IN_PROGRESS, HOLD, VERIFIED, FAILED.
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.11, \
    "exchange_rate": 0.1111, \
    "recipient_amount": 0.01, \
    "fee_amount": 0, \
    "bonus_amount": 0.00, \
    "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.11,
  "exchange_rate": 0.1111,
  "recipient_amount": 0.01,
  "fee_amount": 0,
  "bonus_amount": 0.00,
  "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",
  "three_ds": {
        "enabled": true,
        "status": "string"
  },
}
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.11, \
    "exchange_rate": 0.1111, \
    "recipient_amount": 0.01, \
    "fee_amount": 0, \
    "bonus_amount": 0.00, \
    "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.11,
  "exchange_rate": 0.1111,
  "recipient_amount": 0.01,
  "fee_amount": 0,
  "bonus_amount": 0.00,
  "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",
  "payout_reference_number" : "string",
  "risk_score": 0,
  "payout_method": "CASH_PICKUP"
}

Calculation Mode

There are two calculation modes available for the sending and receiving amount while creating a transaction. These modes are based on which amount (sending or receiving) the system will take as a base for the calculation.

  1. SENDER_AMOUNT: When a transaction is created with this calculation mode, you will pass the sending amount and exchange rate through the Transaction API. The receiving amount is calculated based on the provided sending amount and exchange rate. The default calculation mode is SENDER_AMOUNT.

  2. RECEIVER_AMOUNT: When a transaction is created with this calculation mode, you will pass the total receiving amount, sending amount, and exchange rate through the Transaction API. We will then calculate the sending amount based on the provided receiving amount and exchange rate.

     The calculated sending amount will then be compared with the sending amount you have provided in the request. If the difference between the  calculated sending amount and the sending amount provided by you in the API request is greater than $0.01, the transaction API will provide  the following error message.

    {
  "test_field": "test_value",
  "status": 400,
  "message": "Sender amount is not equivalent with recipient amount."
}

     For example, if the exchange rate today for USD to MEX, is 26.77 and the recipient_amount is 946, the sender amount would be 943/26.77 =  35.338. Since our API will take the difference up to $0.01, $35.34 would be accepted for a successful transaction.

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.11,
  "exchange_rate": 0.1111,
  "recipient_amount": 0.01,
  "fee_amount": 0,
  "bonus_amount": 0.00,
  "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:

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

Delivery Authorization

Click here for Transaction Payout Authorization

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.
sender_verification_halted When the sender verification has been halted
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_in_processing When transaction is ready for processing
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.
bank_verified When the sender's bank account has been verified.
bank_verification_failed When the sender's bank verification has been failed.
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.
fee_approved When the fee change has been approved.
tier_approved When the requested tier upgrade has been approved.
tier_retry When admin has requested to retry the tier upgrade
tier_document_required When admin request for the tier document
tier_disapproved When admin disapproves a tier upgrade request.
tier_canceled When admin cancels a tier upgrade request.
tier_downgraded When admin downgrades a sender’s tier.
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_authorized When the transaction is authorized to deliver by the affiliate. This will be sent for those affiliate who delivers the transaction by themselves.
transaction_delivery_payout_ready When the transaction is ready for pick up by the recipient.
transaction_delivery_failed When the delivery of transaction has failed.
transaction_delivered When the funds have been successfully delivered to the recipient.
sender_profile_edit_submitted Admin has requested for a sender profile edit.
sender_profile_edit_approved Sender profile edit request has been approved.
sender_profile_edit_disapproved Sender profile edit request has been disapproved.
sender_profile_edit_updated Sender profile edit request has been updated.
receiver_profile_edit_submitted Admin has requested for receiver profile edit.
receiver_profile_edit_approved Receiver profile edit request has been approved.
receiver_profile_edit_disapproved Receiver profile edit request has been disapproved.
receiver_profile_edit_updated Receiver profile edit request has been updated.
receiver_account_edit_submitted Admin has requested for receiver account edit.
receiver_account_edit_approved Receiver account edit request has been approved.
receiver_account_edit_disapproved Receiver account edit request has been disapproved.
receiver_account_edit_updated Receiver account edit request has been updated.
3ds_verification_required 3DS verification is required to forward the transaction for processing.

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

{
  "persisted_object_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",
  "timestamp": "2017-07-02T22:88:12.120Z"
}

Webhook PayLoad Request For Receiver Profile Edit

{
  "persisted_object_id": "185bb745-ca07-4e49-984c-7573fd1230b1",
  "resource_id": "4c737c13-a452-4f39-82b1-83c15369bcdd",
  "sender_id": "534a5efe-64f8-4dc6-a6ce-14cfb213e1ab",
  "receiver_id": "38297cec-cb9c-4af6-aff7-f1334990b73c",
  "event_name": "receiver_profile_edit_submitted",
  "subscription_id": "e85db7bc-c14a-484b-8ce9-6d6b48fda4f0",
  "timestamp": "2021-09-01T09:29:38.969"
}

DETAILS

Parameter Description
x-raas-webhook-signature We generate a signature using the secret mentioned on Subscription API.
x-raas-event Event Name
persisted_object_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.
subscription_id Subscription Id for which this event was generated.
receiver_id If receiver related resources are triggered as part of an event then receiver_id will be sent as part of the payload. This is only visible in the receiver profile edit webhook.

For sender_profile_edit_approved and receiver_profile_edit_approved, it is suggested to sync the updated details using Get Sender By Id or Get Receiver By Id

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:

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
Visa Exempted 4000056655665556 Card Successfully Added
Visa Regulated 4005519200000004 Card Successfully Added
Visa Regulated 4000000760000002 Card Successfully Added
Visa Exempted 4500600000000061 Card Successfully Added
Visa Debit Card 4217651111111119 Pull Transaction Not Supported
MasterCard Exempted 2223000048400011 Card Successfully Added
MasterCard Regulated 5200828282828210 Card Successfully Added
MoneySend Debit Card 2223003122003222 Pull Transaction Not Supported
MoneySend Debit Card 5555555555554444 Pull Transaction Not Supported
American Express Debit Card 371449635398431 Pull Transaction Not Supported
Discover Debit Card 6011111111111117 Pull Transaction Not Supported
Visa Credit Card 4111111111111111 Card 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
10 (Including Fee) Failed
Other Processed

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.

References

AVS Response Codes

Code Visa MasterCard Discover American Express
Y Address & 5-digit or 9-digit ZIP match Address & 5-digit ZIP match Address only matches Address & ZIP match
A Address matches, ZIP does not Address matches, ZIP does not Address & 5-digit ZIP match Address only matches
S AVS not supported AVS not supported AVS not supported AVS not supported
R System unavailable, retry System unavailable, retry Not applicable System unavailable, retry
U Information not available Information not available System unavailable, retry Information not available
Z Either 5-digit or 9-digit ZIP match, address does not 5-digit ZIP matches, address does not 5-digit ZIP matches, address does not ZIP code only matches
N Neither ZIP nor address match Neither ZIP nor address match Neither ZIP nor address match Neither ZIP nor address match
W Not applicable For U.S., 9-digit ZIP matches, address does not. For non-U.S., ZIP matches, address does not Information not available Not applicable
X Not applicable For U.S., all digits match. For non-U.S., ZIP and address match. Address & 9-digit ZIP match Not applicable
B Address matches, ZIP not verified Not applicable Not applicable Not applicable
T Not applicable Not applicable 9-digit ZIP matches, address does not Not applicable
P ZIP matches, address not verified Not applicable Not applicable Not applicable
C Address and ZIP not verified Not applicable Not applicable Not applicable
D Address & ZIP match (International only) Not applicable Not applicable Not applicable
G Address not verified for International transaction (International only) Not applicable Not applicable Not applicable
I Address not verified (International only) Not applicable Not applicable Not applicable
M Address & ZIP match (International only) Not applicable Not applicable Not applicable
F Address & ZIP match (UK only) Not applicable Not applicable Not applicable

Changelog

Version 1.18

March 14, 2023

Version 1.17

March 2, 2023

Version 1.16

March 1, 2023

Version 1.15

February 28, 2023

Version 1.14

September 2, 2022

Version 1.13

August 24, 2022

Version 1.12

January 28, 2022

Version 1.11

January 7, 2022

Version 1.10

October 22, 2021

Version 1.9

September 22, 2021

Version 1.8

September 7, 2021

Version 1.7

June 17, 2021

Version 1.6

February 19, 2021

Version 1.5

October 01, 2020

Version 1.4

September 15, 2020

Version 1.3

October 10, 2019

Version 1.2

August 27, 2019

Version 1.1

July 24, 2019

Version 1.0

July 5, 2019

Shell HTTP JavaScript Ruby Python