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.

Customers

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 No String City of the sender
zipcode No 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

  1. Include the Widget Script

Include the Widget

  <script src="https://sandbox.v3api.machpay.com/v3/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/card",
      locale: "en",
      multiStep: true,
      stylesheet: "https://example.com/mystyle.css",
      token: "{{token}}",
    });
    widget.init();
  </script>

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

Funding Source

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”.

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

{
    "id": "UUID",
    "sender_id": "UUID",
    "account_holder_name": "Tenzin Norgay",
    "funding_source_name": "Plaid savings",
    "funding_source_type": "BANK/CARD",
    "institution_name": "Chase",
    "verification_status": "VERIFIED"
}

HTTP Request

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

Recipients

Add a 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

Add a 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 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

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

Create Transaction

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

EXAMPLE REQUEST

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_funding_account_id": "UUID",
    "recipient_id": "UUID",
    "recipient_account_id": "UUID",
    "sender_amount": "Numeric",
    "exchange_rate": "Numeric",
    "fee_amount": "Numeric",
    "recipient_currency": "USD",
    "funding_purpose": "String",
    "ip_address": "10.8.3.64",
    "funding_source" : "BANK",
    "ach_type":"DEBIT / CREDIT"
}'

RESPONSE

[
    {
        "id": "UUID",
        "sender_id": "UUID",
        "sender_funding_account_id": "UUID",
        "recipient_id": "UUID",
        "recipient_account_id": "UUID",
        "sender_amount": 100.00,
        "fee_amount": 0,
        "exchange_rate": 0,
        "recipient_currency": "USD",
        "funding_source": "BANK",
        "ip_address": "10.8.3.64",
        "funding_purpose": "String",
        "status": "INITIATED", 
        "ach_type": "DEBIT/CREDIT"
    }
]

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.
ip_address No String Sender's IP address when the transaction was created.

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

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

[
    {
        "id": "UUID",
        "sender_id": "UUID",
        "sender_funding_account_id": "UUID",
        "recipient_id": "UUID",
        "recipient_account_id": "UUID",
        "reference_number": "String",
        "sender_amount": 100.00,
        "exchange_rate": 0,
        "fee_amount": 0,
        "recipient_currency": "USD",
        "funding_source": "BANK",
        "ip_address": "10.8.3.64",
        "funding_purpose": "String",
        "status": "COMPLETED", 
        "ach_type": "DEBIT / CREDIT"
    }
]

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.

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

Webhooks 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

{
  "id": "82646f2c-447a-4214-a6ad-7d43e87d7fc4",
  "resource_id": "dab8da2c-61ea-42cf-a7c5-223967bebb81",
  "sender_id": "ee3aa0ac-8d18-4a7b-adaf-c5cc8a8db62f",
  "event_name": "transaction_completed",
  "subscription_id": "caec6725-bf0a-4ca4-9f8c-153f4da87259",
  "event_id": "cf8ae9f3-dc8b-4317-8307-a0d71294e9a7",
  "timestamp": "2017-07-02T22:88:12.120Z"
}
Parameter Description
x-raas-webhook-signature We generate a signature using the secret mentioned on the Subscription API.
x-raas-event Event Name
id Webhook unique identifier
event_name Event name. Same as that of header x-raas-event
resource_id Id of 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 Kittn 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 kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! 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.