NAV
shell

MachPay API Documentation

Welcome to MachPay programmable API. MachPay's API docs outlines the details for successfully implementing our integrated API into your application. Our API will enable you to get started with payment solution into your platform in 4 simple steps:

  1. Create a customer/sender
  2. Attach a funding source
  3. Add or select a recipient
  4. Initiate a payment

To make it easier to get familiar with our APIs, we've published a Postman Collection so that you can see examples of all of MachPay APIs in one place.

Authentication

MachPay uses API keys to allow access to the API.

Machnet shall provide you with a set of keys viz., CLIENT_ID and CLIENT_SECRET. You must X-Client-Id and X-Client-Secret in every API request header. These values should never be used publicly and should be stored properly in an encrypted format.

X-Client-Id CLIENT_ID

X-Client-Secret CLIENT_SECRET

Please contact our Sales to get started.

Sender

Register a Sender

This end point creates a new sender. A unique identifier "ID" will be generated as a response which will be used as the "Sender ID" in other end points as well.

EXAMPLE REQUEST

curl --location --request POST 'https://sandbox.v3api.machpay.com/v3/senders' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "first_name": "Tenzin", 
    "middle_name": "M", 
    "last_name": "Norgay", 
    "gender": "male", 
    "mobile_phone": "222-333-4567",
    "type": "INDIVIDUAL",
    "email": "Tenzin.Norgay@everest.com", 
    "address_line1": "21 California Ave",
    "address_line2": "",
    "city": "Irvine",
    "zipcode": "92612",
    "state": "CA",
    "country": "US"
}'

RESPONSE

{
    "first_name": "Tenzin",
    "middle_name": "M",
    "last_name": "Norgay",
    "id": "12345678-abcd-1234-abcd-12345678abcd",
    "mobile_phone": "222-333-4567",
    "email": "Tenzin.Norgay@everest.com",
    "address_line1": "21 California Ave",
    "address_line2": "",
    "city": "Irvine",
    "zipcode": "92612",
    "state": "CA",
    "country": "US",
    "type": "INDIVIDUAL",
    "status": "VERIFIED"
}

HTTP Request

POST 'https://sandbox.v3api.machpay.com/v3/senders

Query Parameters

Parameter Required Type Description
first_name Yes String First name of the sender
middle_name No String Middle name of the sender
last_name Yes String Family name of the sender
email Yes String Email address of the sender
type Yes String INDIVIDUAL/ BUSINESS based on the type of sender
mobile_phone Yes Numeric 10 digits mobile number of the sender
gender No String Gender of the sender
address_line1 Yes String Streeet address of the sender
address_line2 No String Streeet address Line 2 of the sender
city Yes String City of the sender
zipcode Yes Numeric Zipcode of the sender's address
state Yes String 2-letter ISO code of the sender's state.
country Yes String 2-letter ISO code of the sender's country

Update Sender CIP Information

This end point is used to patch/update sender information.

EXAMPLE REQUEST

curl --location --request PATCH 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/cip-info' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "first_name": "Tenzin", 
    "middle_name": "M", 
    "last_name": "Norgay", 
    "gender": "male",
    "mobile_phone": "222-333-4567",
    "email": "Tenzin.Norgay@everest.com", 
    "address_line1": "21 California Ave",
    "address_line2": "",
    "city": "Irvine",
    "zipcode": "92612",
    "state": "CA",
    "country": "US",
    "status":"VERIFIED"
}'

RESPONSE

{
    "first_name": "Tenzin",
    "middle_name": "M",
    "last_name": "Norgay",
    "gender": "male",
    "mobile_phone": "222-333-4567",
    "email": "Tenzin.Norgay@everest.com",
    "address_line1": "21 California Ave",
    "address_line2": "",
    "city": "Irvine",
    "zipcode": "92612",
    "state": "CA",
    "country": "US",
    "status": "VERIFIED"
}

HTTP Request

PATCH 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/cip-info

Widgets

The widget is provided for adding a source of funds. Funds can be added either using a card (Debit) or a bank account (ACH). The widget directs the sender to a third party partner to complete the addition of funding source.

Widget Token

EXAMPLE REQUEST

curl --location --request GET 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/widget-token' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json'

RESPONSE

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

HTTP Request

GET https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/widget-token

Parameter Required Type Description
token Yes String Token details
senderId Yes UUID Sender ID
expiry_minutes Yes Numeric Token validity time

Widget Setup

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

  1. Include the Widget Script

Include the Widget 

  <script src="https://widget.sandbox.v3api.machpay.com/widget/widget.js" charset="utf-8"></script>
  1. Create a div where widget needs to be placed.

Create a div

  <div id="widget-root"> </div>
  1. Initialize the Widget

Initialize the Widget

  <script>
    var widget = new MachnetWidget({
      elementId: "widget-root",
      senderId: "{{senderId}}",
      width: "100%",
      height: "200px",
      type: "bank",
      locale: "en",
      multiStep: true,
      stylesheet: "https://example.com/mystyle.css",
      token: "{{token}}",
    });
    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.
bankId No String bankId for which credential needs to be updated.
transactionId No String transactionId for initializing the 3DS widget.
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.
bank, card, card-push, 3ds.
For example, if bank is provided then the Add Bank 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.

Widget Events

Event Name Widget Type Description
BANK_ADDED bank Sender bank added successfully.
BANK_ERROR bank Sender bank could not be added at the moment. Please try again later.
EXIT_EVENT bank Sender bank could not be added at the moment. Please try again later.
CARD_ADDED card Sender card added successfully.
CARD_ERROR card Sender card could not be added at the moment. Please try again later.
CARD_ADD_LIMIT_EXCEEDED card User has exceeded the 7 day or 30 day card add attempt limit. To add a new card, user will need to wait until the appropriate time period has passed.
THREE_DS_VERIFIED 3ds 3DS verification has been successfully completed through challenge or frictionless flow. The transaction will be forwarded for processing.
THREE_DS_HOLD 3ds 3DS verification is on hold due to an error in the 3DS verification process. Machnet’s admin needs to review the transaction. Please contact Machnet customer support.

If an admin chooses to unhold such transactions, 3DS verification will need to be conducted again. Please review the webhooks section for additional details.
THREE_DS_FAILED 3ds 3DS verification failed as the issuer was not able to verify the transaction. Transaction will be canceled.
THREE_DS_IN_PROGRESS 3ds 3DS verification was initiated and is currently in progress.

Add Bank Widget

This widget will be accessible after the sender is successfully registered on Machnet platform. This widget can be triggered by passing widget type as bank. With this widget, Sender can add their bank accounts.

Add Card Widget

This widget will be accessible after the sender is successfully registered on Machnet platform. This widget can be triggered by passing widget type as card. With this widget, Sender can add their debit cards and will be eligible for Push/Pull, Pull or Push transactions.

Add Card- Push Widget

This widget will be accessible after the sender is successfully registered on Machnet platform. This widget can be triggered by passing widget type as card-push. With this widget, Sender can add debit cards and will be eligible for Push transactions.

3DS Widget

This widget will be accessible after card txn of interchange_type: Debit 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.

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 bank_login_required. In this case, the widget needs to be initialized using the bankId.

Funding Account

Get Funding Source

After the funding source has been added for the sender, this API end point provides the details of the type of funding source added for the sender. The type of funding source can be “BANK” or “CARD”.

Bank

EXAMPLE REQUEST

curl --location --request GET 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/funding-sources?type=BANK' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json'

RESPONSE

{
    "account_holder_name": "String",
    "account_number": "8142",
    "funding_source_name": "String",
    "funding_source_type": "BANK",
    "id": "UUID",
    "institution_name": "String",
    "sender_id": "UUID",
    "verification_status": "String"
}

HTTP Request

GET https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/funding-sources?type=BANK

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 VERIFIED, FAILED, LOGIN_REQUIRED
funding_source_type string Enumerated value BANK

Guide for Bank Authentication

Click here for Oauth Bank Authentication

Card

EXAMPLE REQUEST

curl --location --request GET 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/funding-sources?type=CARD' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json'

RESPONSE

[
    {
        "availability": "String",
        "avs_code": "Y",
        "card_type": "PULL|PUSH",
        "duplicate_account_info": [
            {
                "funding_account_id": "UUID",
                "funding_account_name": "String",
                "sender_id": "UUID",
                "sender_name": "String"
            }
        ],
        "duplicate_flagged": true,
        "duplicate_reasons": [
            "String"
        ],
        "funding_source_name": "0002-Visa",
        "funding_source_type": "CARD",
        "id": "UUID",
        "institution_name": "String",
        "regulated": true,
        "sender_id": "UUID"
    },
    {
        "availability": "String",
        "avs_code": "Y",
        "card_type": "PUSH",
        "funding_source_name": "1119-Visa",
        "funding_source_type": "CARD",
        "id": "UUID",
        "institution_name": "String",
        "regulated": false,
        "sender_id": "UUID"
    },
    {
        "avs_code": "Y",
        "card_type": "PULL",
        "funding_source_name": "0011-MasterCard",
        "funding_source_type": "CARD",
        "id": "UUID",
        "institution_name": "String",
        "regulated": true,
        "sender_id": "UUID"
    }
]

HTTP Request

GET https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/funding-sources?type=CARD

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
institution_name string Name of the institution/bank associated with the account
funding_source_type string Enumerated value CARD
card_type string Enumerated value PULL, PUSH, PULL|PUSH
availability string Estimated Funds Availability
regulated boolean Represents if the card is regulated or not
avs_code string AVS Response Code of the Card. For Reference: AVS Code for Card
duplicate_flagged boolean true if another sender within the Affiliate or across the Machnet system has added the same card. Only applicable to card funding account.
duplicate_reasons string Details on whether the sender that has added the duplicate card is within the Affiliate or across the Machnet system. Reasons: "Duplicate card was found within client", "Duplicate card was found in the platform"
duplicate_account_info object Details of accounts that are duplicate with the added card. Details are only provided of accounts and their associated user if it is duplicate within the Affiliate.

If the card is duplicate across the Machnet system, account information details are not provided.
duplicate_account_info.send
er_id		 UUID Sender ID associated with the card that is duplicate to the added card.
duplicate_account_info.send
er_name		 string Sender name associated with the card that is duplicate to the added card.
duplicate_account_info.fund
ing_account_id		 UUID ID of the card that is duplicate to the added card.
duplicate_account_info.fund
ing_account_name		 string Name the card that is duplicate to the added card.

Delete Sender Funding Account

This API end point deletes the funding account associated with the sender.

HTTP Request

GET https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/funding-sources/{fundingAccountId}

EXAMPLE REQUEST

curl --location --request DELETE 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/funding-sources/{{fundingAccountId}}' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json'

RESPONSE

HTTP Status 204 (No content)

Recipient

Add Recipient

This API end-point will let you add a recipient.

EXAMPLE REQUEST

curl --location --request POST 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/recipients' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "first_name": "Edmund", 
    "middle_name": "M", 
    "last_name": "Hillary", 
    "mobile_phone": "111-222-3456",
    "type": "INDIVIDUAL / BUSINESS",
    "email": "Edmund.Hillary@everest.com", 
    "address_line1": "32 California Ave",
    "city": "Irvine",
    "zipcode": "92612",
    "state": "CA", 
    "country": "US",
    "sender_relationship": "Friend"
 }'

Response

{
    "id": "UUID",
    "sender_id": "UUID",
    "first_name": "Edmund", 
    "middle_name": "M", 
    "last_name": "Hillary", 
    "mobile_phone": "111-222-3456",
    "email": "Edmund.Hillary@everest.com", 
    "address_line1": "32 California Ave",
    "city": "Irvine",
    "zipcode": "92612",
    "state": "CA", 
    "country": "US",
    "sender_relationship": "Friend"
}

HTTP Request

POST https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/recipients

Parameter Required Type Description
senderId Yes UUID Sender ID
first_name Yes String First name of the recipient
middle_name No String Middle name of the recipient
last_name No String Last name of the reeipient
type No String INDIVIDUAL/ BUSINESS based on the type of recipient
mobile_phone No Numeric 10 digits mobile phone of hge recipient
email No String Email of the recipient
address_line1 No String Current address of the recipient
address_line2 No String Line 2 address of the recipient
city No String City name of recipient
zipcode No Numeric Zipcode of the recipient's address
state No String 2-letter ISO code of the recipient's state.
country No String 2-letter ISO code of the recipient's country
sender_relationship No String Sender relationship to recipient

Get Recipient by Sender ID

This API end-point will let you get recipient details using sender id.

EXAMPLE REQUEST

curl --location --request GET 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/recipients' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json'

RESPONSE:

[
    {
        "id": "UUID",
        "sender_id": "UUID",
        "first_name": "String",
        "address_line1": "String",
        "city": "String",
        "country": "String",
        "email": "String",  
        "sender_relationship": "String"
    },
    {
        "id": "UUID",
        "sender_id": "UUID",
        "first_name": "String",
        "address_line1": "String",
        "city": "String",
        "country": "String",
        "email": "String",  
        "sender_relationship": "String"
    }
]

HTTP Request

GET https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/recipients

Recipient Account

Add Recipient Account

This API end-point will let you add a recipient account.

EXAMPLE REQUEST

curl --location --request POST 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/recipients/{{recipientId}}/accounts' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account_number":"numeric",
    "rtn_number":"numeric",
    "account_type":"SAVINGS / CHECKING"
}'

Response

{
    "id": "UUID",
    "account_number":"numeric",
    "rtn_number":"numeric",
    "account_type":"SAVINGS / CHECKING"
}

HTTP Request

POST https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/recipients/{{recipientId}}/accounts

Parameter Required Type Description
senderId Yes UUID Sender ID
recipientId Yes UUID Recipient ID
account_number Yes Numeric Account number of the recipient
rtn_number Yes Numeric Routing number of the recipient
account_type Yes String Savings / Checking account

Get Recipient Account

This API end-point will get recipient's account details using recipient ID.

EXAMPLE REQUEST

curl --location --request GET 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/recipients/{{recipientId}}/accounts' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json'

RESPONSE

[
    {
        "id": "UUID",
        "account_number": "numeric",
        "account_type": "SAVINGS",
        "rtn_number": "numeric"
    }
]

HTTP Request

GET https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/recipients/{{recipientId}}/accounts

Transactions

Transaction hold information

Code Message Description
T001 Transaction is under review Transaction is under compliance review. Please contact customer support.
T002 Service limit exceeded Service limit exceeded. Please contact Machnet customer support
T003 Unable to check balance Balance of the user’s funding source could not be checked. This increases chances of NSF. Please contact customer support
T004 Unable to conduct card verification. Please contact customer support Card verification of the user could not be completed. Please contact customer support.
T005 AML not connected Required compliance checks could not be conducted. Please contact customer support.
T006 Card used to fund the transaction is duplicate with other users within the same affiliate. Transaction is under review as card used to fund the transaction is duplicate with other users within the same affiliate.

Create Transaction

This API end-point will initiate a transaction from sender to receiver account.

EXAMPLE REQUEST for Create BANK Transaction

curl --location --request POST 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/transactions' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sender_amount": 100.00,
    "exchange_rate": 1,
    "fee_amount": 0,
    "sender_funding_account_id":"UUID",
    "recipient_id": "UUID",
    "recipient_account_id": "UUID",
    "recipient_currency": "USD",
    "funding_purpose": "String",
    "ip_address": "10.8.3.64",
    "funding_source" : "BANK",
    "ach_type":"DEBIT"
}'

RESPONSE

{
    "ach_type": "DEBIT",
    "created_at": "2021-11-10T09:23:15.441",
    "exchange_rate": 1,
    "fee_amount": 0,
    "funding_purpose": "String",
    "funding_source": "BANK",
    "id": "UUID",
    "ip_address": "10.8.3.64",
    "recipient_account_id": "UUID",
    "recipient_currency": "USD",
    "recipient_id": "UUID",
    "sender_amount": 100.00,
    "sender_funding_account_id": "UUID",
    "sender_id": "UUID",
    "status": "INITIATED"
}

EXAMPLE REQUEST for Create Card Transaction

curl --location --request POST 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/transactions' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sender_amount": 100.00,
    "exchange_rate": 1,
    "fee_amount": 0,
    "sender_funding_account_id":"UUID",
    "recipient_id": "UUID",
    "recipient_account_id": "UUID",
    "recipient_currency": "USD",
    "funding_purpose": "String",
    "ip_address": "10.8.3.64",
    "funding_source" : "CARD",
    "interchange_type": "DEBIT"
}'

RESPONSE

{
    "created_at": "2021-11-10T09:23:15.441",
    "exchange_rate": 1,
    "fee_amount": 0,
    "funding_purpose": "String",
    "funding_source": "CARD",
    "id": "UUID",
    "interchange_type": "DEBIT",
    "ip_address": "10.8.3.64",
    "recipient_account_id": "UUID",
    "recipient_currency": "USD",
    "recipient_id": "UUID",
    "sender_amount": 100.0,
    "sender_funding_account_id": "UUID",
    "sender_id": "UUID",
    "status": "INITIATED",
    "three_ds": {
        "enabled": true,
        "status": "UNVERIFIED"
    }
}

HTTP Request

POST https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/transactions

Query Parameters

Parameter Required Type Description
senderId Yes UUID Sender ID
sender_amount Yes Numeric Sender amount
exchange_rate Yes Numeric Exchange rate used for the transactions
fee_amount No Numeric Transaction Fee
sender_funding_account_id Yes UUID Sender Funding Account ID
recipient_id Yes UUID RecipientID
recipient_account_id Yes UUID Recipient account ID. Receiver account can be a recipient bank account or a Debit Card.
recipient_currency Yes String The currency of the transaction
funding_purpose No String The purpose of sending money
funding_source Yes String Enumerated Value: BANK or CARD. It should be based on the sender funding account type.
ach_type Yes[incase of BANK] String Enumerated Value: DEBIT or CREDIT. It is mandatory to provide when the funding source is BANK. DEBIT will transfer funds from sender to receiver ac and CREDIT vice versa.
interchange_type Yes[incase of CARD] String Enumerated Value: DEBIT or CREDIT. It is mandatory to provide when the funding source is CARD. DEBIT will transfer funds from sender to receiver ac and CREDIT vice versa.
ip_address No String Sender's IP address when the transaction was created.
authorization_code No Numeric Code generated by the issuing bank after making a transaction. Received for Card transaction only.
remarks No String Transaction Cancelation reason. Received only for CANCELED transaction.
status Yes String Status of the transaction. Enumerated Value: INITIATED, PENDING, HOLD, COMPLETED, CANCELED, REFUNDED, RETURNED, FAILED.
three_ds.enabled Yes[incase of CARD] Boolean Represents if the 3DS service is configured or not.
three_ds.status No String Enumerated value UNVERIFIED, IN_PROGRESS, HOLD, VERIFIED, FAILED.

Get Transaction by ID

This API is used to fetch the transaction details using the transaction’s UUID. The transaction reference number is generated only after the transaction is in 'PENDING' status.

EXAMPLE REQUEST for BANK Transaction

curl --location --request GET 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/transactions/{{transactionId}}' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json'

RESPONSE

{
    "ach_type": "DEBIT",
    "created_at": "2021-11-10T09:23:15.441",
    "exchange_rate": 1,
    "fee_amount": 0,
    "funding_purpose": "String",
    "funding_source": "BANK",
    "id": "UUID",
    "ip_address": "10.8.3.64",
    "recipient_account_id": "UUID",
    "recipient_currency": "USD",
    "recipient_id": "UUID",
    "reference_number": "String",
    "risk_score": 1,
    "sender_amount": 100.00,
    "sender_funding_account_id": "UUID",
    "sender_id": "UUID",
    "status": "COMPLETED"
}

EXAMPLE REQUEST for CARD Transaction

curl --location --request GET 'https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/transactions/{{transactionId}}' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json'

RESPONSE

{
    "authorization_code": "Numeric",
    "created_at": "2021-11-10T09:23:15.441",
    "exchange_rate": 1,
    "fee_amount": 0,
    "funding_purpose": "String",
    "funding_source": "CARD",
    "id": "UUID",
    "interchange_type": "DEBIT",
    "ip_address": "10.8.3.64",
    "recipient_account_id": "UUID",
    "recipient_currency": "USD",
    "recipient_id": "UUID",
    "reference_number": "String",
    "risk_score": 1,
    "sender_amount": 100.00,
    "sender_funding_account_id": "UUID",
    "sender_id": "UUID",
    "status": "COMPLETED",
    "three_ds": {
        "enabled": true,
        "status": "VERIFIED"
    }
}

HTTP Request

GET https://sandbox.v3api.machpay.com/v3/senders/{{senderId}}/transactions/{{transactionId}}

Cancel Transaction

This API is used to Cancel the transaction for the Sender. Debit Card Transactions cannot be cancelled. ACH transactions with the status 'INITITATED' and 'PENDING' can be cancelled.

EXAMPLE REQUEST

curl --location --request DELETE 'https://api.machpay.com/v3/senders/{{senderId}}/transactions/{{transactionId}}' \
--header 'X-Client-Id: {{client_id}}' \
--header 'X-Client-Secret: {{client_secret}}' \
--header 'Content-Type: application/json' \

RESPONSE

HTTP Status 204 (No content)

HTTP Request

DELETE 'https://api.machpay.com/v3/senders/{{senderId}}/transactions/{{transactionId}}

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.

Webhook Events

Status Name Webhook Event Description Occurence
INITIATED No Webhook The transaction request has been submitted. Picked up to be processed from the Queue.
PENDING transaction_created The transaction is selected for processing. Is being processed for third party services.
COMPLETED transaction_completed, transaction_processed The transaction has been Processed successfully. Both webhooks will be sent.
FAILED transaction_failed The transaction was unable to be Processed.
CANCELED transaction_canceled The transaction was cancelled by the user or admin.
HOLD transaction_onhold The sender's transaction is on hold due to some reason and the hold reason is provided in the response when fetching transaction information.
RETURNED transaction_returned When the transaction has been returned.
REFUNDED transaction_refunded The funds have been credited back to the Sender's Funding Account.
LOGIN_REQUIRED bank_login_required When the sender needs to update their bank credentials.
VERIFIED bank_added When the sender's Bank has been added successfully.
N/A bank_removed When the sender's Bank has been removed.
FAILED bank_verification_failed When the sender's bank verification has been failed.
VERIFIED card_added When the sender's Card has been added successfully.
N/A duplicate_card_added When sender adds a card that has already been added by another sender within the Affiliate or across the Machnet platform.
N/A card_removed When the sender's Card has been removed.
N/A card_deactivated When the sender's Card has been deactivated.
N/A sender_registered When a sender has been created successfully.
N/A sender_cip_info_updated When a sender's cip information is updated.
UNVERIFIED 3ds_verification_required 3DS verification is required to forward the transaction for processing.

Webhook Integration

After the Subscription API has been set up, webhooks are 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

{
    "event_name": "transaction_completed",
    "persisted_object_id": "b34580cb-68fd-4eae-a293-f14321bb01b9",
    "resource_id": "49af82ed-abb3-482d-8759-e56cf0f17ee5",
    "sender_id": "35fd73f2-28f5-4245-9b4c-239381a31251",
    "subscription_id": "ddf7b6f3-e0e7-4433-b980-2ca527c1eb0f",
    "timestamp": "2022-01-27T10:50:55.503"
}
Parameter Description
x-raas-webhook-signature We generate a signature using the secret mentioned on the Subscription API.
x-raas-event Event Name
event_name Event name. Same as that of header x-raas-event
persisted_object_id Webhook unique identifier
resource_id Id of the 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.

Securing Webhooks

We allow you to set the 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 a 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.

Webhooks Subscription

Subscribe Webhook

EXAMPLE REQUEST

  curl --location --request POST 'https://sandbox.v3api.machpay.com/v3/subscriptions' \
  --header 'X-Client-Id: {{client_id}}' \
  --header 'X-Client-Secret: {{client_secret}}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "end_point": url,
    "secret": UUID
  }'

The returned JSON response is structured like this:

[
    {
        "end_point": "url",
        "secret": "UUID",
        "active_from": "2021-03-10 05:49:51",
        "id": "UUID",
        "is_active": true,
        "is_paused": false
    }
]

HTTP Request

POST https://sandbox.v3api.machpay.com/v3/subscriptions

Query Parameters

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

Errors

The API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The specified request is hidden for administrators only.
404 Not Found -- The specified request could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The requested resource has been removed from our servers.
429 Too Many Requests -- You're requesting too many resources! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Test Values For Sandbox

Test values for Bank Addition

Case username password
To generate same account number/routing number user_good pass_good
To generate unique account info user_custom {}
To generate a specific type of account and balance user_custom {"override_accounts":[{"force_available_balance":500,"type":"depository","subtype":"checking"}]}

Test values for Card Addition

Network Card Number Type PULL PUSH
Visa 4000056655665556 Debit Card ✔ ✔
Visa 4005519200000004 Debit Card ✔ ✔
Visa 4000000760000002 Debit Card ✔ ✔
Visa 4500600000000061 Debit Card ✔ ✔
Visa 4217651111111119 Debit Card ✘ ✔
MasterCard 2223000048400011 Debit Card ✔ ✘
MasterCard 5200828282828210 Debit Card ✔ ✘
MoneySend 2223003122003222 Debit Card ✘ ✔
MoneySend 5555555555554444 Debit Card ✘ ✘
American Express 371449635398431 Debit Card ✘ ✘
Discover 6011111111111117 Debit Card ✘ ✘
Visa 4111111111111111 Credit Card ✔ ✔

Test values for 3DS Verification

Card Number Network Type 3ds verification flow Results
4000056655665556 Visa Frictionless 3DS verification status will be FAILED and transaction will be Canceled.
2223000048400011 MasterCard Frictionless 3DS verification status will be FAILED and transaction will be Canceled.
4005519200000004 Visa Frictionless 3DS verification status will be VERIFIED and transaction will be further processed.
5200828282828210 MasterCard Frictionless 3DS verification status will be VERIFIED and transaction will be further processed.
4000000000002446 Visa Frictionless 3DS verification status will be FAILED and transaction will be Canceled.
4000000000002354 Visa Frictionless 3DS verification status will be FAILED and transaction will be Canceled.
4500600000000061 Visa Frictionless 3DS verification status will be FAILED and transaction will be Canceled.
4000000760000002 Visa Challenge 3DS verification status will be VERIFIED if correct authentication code is passed and transaction will be further processed.

Test values for Transaction Status Change

For Bank Transaction

Transaction Amount Transaction Status
All values except below mentioned COMPLETED
55 RETURNED
99 FAILED

For Card Transaction

Transaction Amount Transaction Status
10 CANCELED
20 HOLD
Any other value except above mentioned COMPLETED

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 2.0

April 08, 2024

Version 1.9

August 01, 2023

Version 1.8

July 18, 2023

Version 1.7

May 17, 2023

Version 1.6

April 27, 2022

Version 1.5

March 07, 2022

Version 1.4

February 16, 2022

Version 1.3

January 24, 2022

Version 1.2

December 21, 2021

Version 1.1

November 01, 2021

shell