# Getting Started Hello and welcome to Machnet's API docs! Our API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). These API docs outline the end-points and integration details to successfully integrate our product to build your kick-ass FinTech application. Happy building! Ready to get started? Sign up [here](https://sandbox.machnetinc.com/) at our sandbox to get immediate access and start building with Machnet. ## **What is Machnet and what do we do?** Machnet is an "All-in-One banking, compliance, payment, and payout infrastructure - reimagined and built for cross-border businesses". We enable companies by providing license and compliance infrastructure along with banking and payment rails to move money across borders from the US and Canada. Our solution also removes the obstacles and challenges you face when integrating with multiple 3P solutions. With our single integrated API, you can get up and running as quickly as 2 weeks. ![](https://3352460685-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlUAZApNcLx8HhAlPHT%2Fuploads%2FkkWWGh6azcumNp5DABCw%2Funnamed.png?alt=media\&token=2c8c6c19-3b98-4cc0-b4f6-fced25a5470e) You will have to use the following URL to access our sandbox: Use our postman collection to quickly run through our API endpoints [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/14929752-9645305f-ac9a-4a7f-8192-9da33f2396bf?action=collection%2Ffork\&collection-url=entityId%3D14929752-9645305f-ac9a-4a7f-8192-9da33f2396bf%26entityType%3Dcollection%26workspaceId%3Debc93fa9-5af7-4809-9d6f-3db9c0e6d0bd#?env%5BPaaS%20Sandbox%5D=W3sia2V5IjoidXJsIiwidmFsdWUiOiJodHRwczovL3Y0c2FuZGJveC5tYWNocGF5LmNvbS92NCIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJ0ZXh0In0seyJrZXkiOiJjbGllbnRfaWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJ0ZXh0In0seyJrZXkiOiJjbGllbnRfc2VjcmV0IiwidmFsdWUiOiJjNTYyNDM1ZS1jYjgwLTRkZjEtYWExMS0yMDVhMmRmNTZiNmEiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoidGV4dCJ9LHsia2V5IjoiZW1haWwiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJ0ZXh0In0seyJrZXkiOiJ1c2VySWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJ0ZXh0In0seyJrZXkiOiJ0b2tlbiIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InRleHQifSx7ImtleSI6ImFjY291bnRJZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InRleHQifSx7ImtleSI6InJlY2VpdmVVc2VySWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJ0ZXh0In0seyJrZXkiOiJyZWNlaXZlVXNlckFjY291bnRJZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InRleHQifSx7ImtleSI6InRyYW5zYWN0aW9uSWQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJ0ZXh0In0seyJrZXkiOiJ0cmFuc2FjdGlvbl9pZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InRleHQifSx7ImtleSI6InJlY2lwaWVudEFjY291bnRJZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InRleHQifSx7ImtleSI6ImFkbWluX2lkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCJ9LHsia2V5IjoiYWRtaW5fc2VjcmV0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCJ9XQ==) Any feedback on our API docs, please help us get better at . Experiencing Technical Issues? Please contact our support at . # Authentication Machnet uses API keys to allow access to our APIs. Machnet will provide you with a set of keys: CLIENT\_ID and CLIENT\_SECRET. You must use X-Client-Id and X-Client-Secret in every API request header. {% hint style="info" %} CLIENT\_ID and CLIENT\_SECRET values should never be used or shared publicly and should be stored properly in an encrypted format. {% endhint %} X-Client-Id: CLIENT\_ID\ X-Client-Secret: CLIENT\_SECRET You will have to use the following URL to access our sandbox: ### Set up your custom API keys If you've downloaded our Postman collection, you should be able to see our API endpoints on the left and the appropriate environment variables on the right. ![](https://3352460685-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlUAZApNcLx8HhAlPHT%2Fuploads%2FKyeact6rgCoDqaEG5lvb%2FScreen%20Shot%202022-06-08%20at%201.12.29%20PM.png?alt=media\&token=437abddf-ea49-4265-be06-45c8786274bc) ### Add Client Keys The next step is to add your own client keys into the environment variables. ![](https://3352460685-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MlUAZApNcLx8HhAlPHT%2Fuploads%2FDs8snxyNNmqyBDGwHlen%2FScreen%20Shot%202022-06-08%20at%201.04.31%20PM.png?alt=media\&token=ba11f1e5-086c-4863-89a0-ed7c448d20e1) # Remittance Read for API integration recommendations for remittance use case. Remittance transactions include processing and delivery of person-to-person transactions. Based on your requirements and agreement with Machnet, you may deliver the transactions yourself. Regardless, these are **external transactions** to external receivers who may be residing in a country different from the sender. ## Integration Recommendations This section will guide you through the API endpoints for the remittance use case. Please note that these are recommendations for standard flow and can be customized as per your needs. ### 1. User Registration The first step in creating the user flow is to [register the user](/api-references/user/registration-1#register-a-user) in our system. Individual users need to be registered with the business field as false. Users can only be registered from the country which has been enabled for you as per your agreement with Machnet. Fields outlined as mandatory in the user object are required during registration. ### 2. User KYC and Transaction Limits You will have to provide user information so that necessary KYC checks can be conducted on the sender. In order to run KYC on the sender, you will have to: 1. Know what [KYC information is required for the sender](/api-references/data-population/spec-sheet) 2. Collect and[ send the required information to Machnet](/api-references/user/user-kyc#update-kyc-information). 3. [Initiate KYC process for the user](/api-references/user/initiate-verification#post-users-user_id-kyc) User's KYC verification is conducted using the following information: * Name * Date of birth * Gender * Address * Email * Phone number Once you have submitted the information, [you check what KYC information has been provided by a user and its verification status](/api-references/user/get-verification-status). Each information required for KYC and tier verification is referred to as a CIP tag and each CIP tag has their own verification status. Only when all CIP tags required for KYC verification (listed above) are verified will the KYC status of the user be verified. Additional information may be required based on the transactions the user wants to create over a period of time. This information is outlined in your spec sheet and can also be obtained using [this API](/api-references/data-population/spec-sheet). You can submit the additional information and update existing information collected from the user using the [Update KYC information API](/api-references/user/user-kyc#update-kyc-information). Each time new information is submitted, make sure to [initiate KYC](/api-references/user/initiate-verification) on the user to ensure verification of all submitted information. ### 3. Add Receive User [A user with the type "RECEIVE" will need to be added](/api-references/user/add-a-receive-user) as the receiver of the transaction. Since remittance transactions only support C2C transaction type, all receive users in remittance transactions need to be individuals. Based on the payout method and corridor of the transaction, different details of the receive user need to be collected. For Bank Deposit and Wallet transactions, the [receive user's account also has to be added](/api-references/funds/add-a-receive-account). The available banks and their details can be obtained using the [Banks API](/api-references/payout/get-banks). All banks which support remittance will have txn\_supported\_types as C2C. Funds will be directly deposited into this account. The available wallets and their details can be obtained using the [Payers API](/api-references/payout/get-payers). For Cash Pickup and Home Delivery, the user will have to select a payer location. The available payer details can be obtained using the [Payers API](/api-references/payout/get-payers). The associated payer\_id for the selected location will have to be used during transaction creation. ### 4. Add Funding Account Once the required transaction information has been collected, the user will then have to [link a funding source for the transaction](/api-references/funds/funding-account-widget). We support bank accounts and debit cards. These are added using a widget to ensure security. For Client approved for wallet product, user's wallet can also be used as a funding source. In order to add wallets for users, please review the [wallet use case guide](/use-cases/individual-wallet). The sender can add a funding account and proceed to create a transaction as long as their KYC status is not UNVERIFIED and IN PROGRESS. ### 5. Submit transaction You are now ready to [create the transaction](/api-references/transaction/create-1). Please note that users with SEND capabilities can only create transactions within the limits set in the CIP documents. The transaction limits available to a user are based on the submitted KYC information and their verification status. All transactions above the user's permitted limits and below the maximum transaction limit is placed on HOLD with the reason [*T004 Transaction Limit Exceeded*](/api-references/transaction/create-1#transaction-hold-reasons). In such cases, the user will need to provide additional information to increase their transaction limits. The verification status of those additional required fields (CIP tags) will be in REQUESTED status. Once this information is submitted, you will need to initiate KYC again for the user. If the submitted information is VERIFIED, the transaction will be forwarded for processing. If the transaction amount exceeds the maximum transaction limit set for a user of a Client, the transaction will be CANCELED. ### 6. Transaction Delivery Even though a transaction has been created, a transaction will not be forwarded for payout to the beneficiary unless you send a [delivery request](/api-references/transaction/transaction-delivery). You can choose to send a delivery request once the funds have been debited from the sender (transaction status: PROCESSED) to contain risks or beforehand to ensure faster payments. If you are delivering the transaction using your own payout network and NOT using our network, you will need to update the delivery status on our system as well. # Bonus/Discount on Remittance Read on building bonus and discount features for your remittance service ## Overview During transaction creation, you can apply a bonus or discount to a particular transaction. Our clients have used this feature to improve their customer acquisition and retention strategies. Based on how you build your application, you can support multiple different use cases for bonus and discount offers. In general, bonus features can be implemented by providing a value for the [“bonus\_amount” field](/api-references/transaction/create) in the [Create Transaction API](/api-references/transaction/create-1). On the Machnet system, the criteria required for transaction creation remains the same for transactions with bonus similar transactions without bonus. However, Clients can build different criteria on their system to provide bonuses based on their use case. The most common implementations are listed below with details on how to build them. ### Implementation 1: Bonus provided to the Receive **User** This implementation allows a transaction to be created with a bonus amount where the bonus amount is provided to the receive user. You can choose to build logics on when to provide this bonus. It could be a first time user or a loyal user who has created 10 transactions already. When your bonus criteria is met, just be sure to include the bonus amount in the “from\_amount” field and provide the bonus amount in the “bonus\_amount” field as well in the Create Transaction API. Detailed examples are below. {% tabs %} {% tab title="Example 1" %} **Bonus amount in sending currency** Amount entered by sender: USD 100 Bonus provided by the client USD 5 | **Field** | **Amount** | **Description** | | ------------------------------------------- | ---------- | --------------------------------------------------- | | from\_amount | USD 105 | Amount entered by sender ($100) + Bonus amount ($5) | | fee\_amount | USD 2 | Fee to be added, if applicable | | bonus\_amount | USD 5 | Bonus provided to the receiver | | Total amount deducted from sender’s account | USD 102 | from\_amount + fee\_amount - bonus\_amount | | exchange\_rate | 14 | Exchange rate (USD 1=GHS 14) | | Total amount received by the receiver | GHS 1470 | from\_amount\*exchange\_rate | **Sample Request** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount":105, "exchange_rate": 14, "to_amount":1470, "fee_amount": 2, "bonus_amount": 5, "note": "Sample Note", "to_currency":"GHS", "from_currency":"USD", "custom_purpose":"home", "purpose": "OTHER", "ip_address": "10.10.10.5", "from_fund_id": UUID, "funding_source_type": "CARD", "to":{ "id": UUID, "fund_id" : UUID, "payout_method":"BANK_DEPOSIT", "calculation_mode":"SENDER_AMOUNT" } }' ``` {% endtab %} {% tab title="Example 2" %} #### Bonus amount in receiving currency Amount entered by sender: USD 100 Discount provided by the client: GHS 140 | **Field** | **Amount** | **Description** | | --------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | | from\_amount | USD 110 | Amount entered by sender (100) + Bonus amount (10) | | fee\_amount | USD 2 | Fee to be added, if applicable | | bonus\_amount | USD 10 |

Discount to be provided to the sender:

Discount provided by Client (GHS 140)/Exchange rate (14)

| | Total amount deducted from sender’s account\* | USD 102 | from\_amount + fee\_amount - bonus\_amount | | exchange\_rate | 14 | Exchange rate (USD 1=GHS 14) | | Total amount received by the receiver | GHS 1540 | from\_amount\*exchange\_rate | **Sample Request** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount":110, "exchange_rate": 14, "to_amount":1540, "fee_amount": 2, "bonus_amount": 10, "note": "Sample Note", "to_currency":"GHS", "from_currency":"USD", "custom_purpose":"home", "purpose": "OTHER", "ip_address": "10.10.10.5", "from_fund_id": UUID, "funding_source_type": "CARD", "to":{ "id": UUID, "fund_id" : UUID, "payout_method":"BANK_DEPOSIT", "calculation_mode":"SENDER_AMOUNT" } }' ``` {% endtab %} {% endtabs %} ### Implementation 2: Discount provided to the Send user This implementation allows a transaction to be created where a discount equal to the bonus amount is provided to the send user. You can choose to build logics on when to provide this discount to your user. It could be a first time user or a loyal user who has created 10 transactions already. When a criteria is met, just be sure to send us the amount you would like to discount in the “bonus\_amount” field in the Create Transaction API. {% tabs %} {% tab title="Example 1" %} **Discount provided to the send user** Amount entered by sender: USD 100 Discount provided by the client: USD 5 | **Field** | **Amount** | **Description** | | --------------------------------------------- | ---------- | ------------------------------------------ | | from\_amount | USD 100 | Amount entered by sender | | fee\_amount | USD 2 | Fee to be added, if applicable | | bonus\_amount | USD 5 | Discount to be provided to the sender | | Total amount deducted from sender’s account\* | USD 97 | from\_amount + fee\_amount - bonus\_amount | | exchange\_rate | 14 | Exchange rate (USD 1=GHS 14) | | Total amount received by the receiver | GHS 1400 | from\_amount\*exchange\_rate | #### Sample Request ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount":100, "exchange_rate": 14, "to_amount":1400, "fee_amount": 2, "bonus_amount": 5, "note": "Sample Note", "to_currency":"GHS", "from_currency":"USD", "custom_purpose":"home", "purpose": "OTHER", "ip_address": "10.10.10.5", "from_fund_id": UUID, "funding_source_type": "CARD", "to":{ "id": UUID, "fund_id" : UUID, "payout_method":"BANK_DEPOSIT", "calculation_mode":"SENDER_AMOUNT" } }' ``` {% endtab %} {% endtabs %} ### Implementation 3: Bonus FX rate You can provide a bonus FX rate to your users to remain competitive in the market. When you create a transaction, you will have to provide us the FX rate applicable to the specific transaction which should include the bonus FX. {% tabs %} {% tab title="Example 1" %} **Provide higher FX to the user** Amount entered by sender: USD USD 100 Exchange rate: USD 1 = GHS 14 Bonus FX provided by the client for the user: USD 1=GHS 20 | **Field** | **Amount** | **Description** | | --------------------------------------------- | ---------- | ----------------------------------------------- | | from\_amount | USD 100 | Amount entered by sender | | fee\_amount | USD 2 | Fee to be added, if applicable | | bonus\_amount | - | Bonus provided to the receiver | | Total amount deducted from sender’s account\* | USD 102 | from\_amount + fee\_amount - bonus\_amount) | | exchange\_rate | 20 | Exchange rate including bonus FX (USD 1=GHS 20) | | Total amount received by the receiver | GHS 2000 | from\_amount\*exchange\_rate | \ **Sample Request** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount":100, "exchange_rate": 20, "to_amount":2000, "fee_amount": 2, "bonus_amount": 0, "note": "Sample Note", "to_currency":"GHS", "from_currency":"USD", "custom_purpose":"home", "purpose": "OTHER", "ip_address": "10.10.10.5", "from_fund_id": UUID, "funding_source_type": "CARD", "to":{ "id": UUID, "fund_id" : UUID, "payout_method":"BANK_DEPOSIT", "calculation_mode":"SENDER_AMOUNT" } }' ``` {% endtab %} {% endtabs %} ### Implementation 4: Waive fees of a transaction As a marketing offer, you can also waive fees fully or partially for a user’s transaction. In order to do so, you will have to provide "bonus\_amount" equal to the total fees or equal to the partial discount you are providing on the fees. {% tabs %} {% tab title="Example 1" %} **Waive partial fees for a transaction** Amount entered by sender: USD 100 Fees: USD 5 Discount on fees provided by the Client to the user: USD 2 | Field | Amount ($) | Description | | --------------------------------------------- | ---------- | ---------------------------------------------------- | | from\_amount | USD 100 | Amount entered by sender | | fee\_amount | USD 3 | Fee to be added after discount on fees (USD 5-USD 2) | | bonus\_amount | 0 | Bonus provided to the receiver | | Total amount deducted from sender’s account\* | USD 103 | from\_amount + fee\_amount - bonus\_amount | | exchange\_rate | 14 | Exchange rate including bonus FX (USD 1=GHS 14) | | Total amount received by the receiver | GHS 1400 | from\_amount\*exchange\_rate | \ **Sample Request** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount":100, "exchange_rate": 14, "to_amount":1400, "fee_amount": 3, "bonus_amount": 0, "note": "Sample Note", "to_currency":"GHS", "from_currency":"USD", "custom_purpose":"home", "purpose": "OTHER", "ip_address": "10.10.10.5", "from_fund_id": UUID, "funding_source_type": "CARD", "to":{ "id": UUID, "fund_id" : UUID, "payout_method":"BANK_DEPOSIT", "calculation_mode":"SENDER_AMOUNT" } }' ``` {% endtab %} {% tab title="Example 2" %} **Waive full fees for a transaction** Amount entered by sender: USD 100 Fees: USD 5 Discount on fees provided by the Client to the user: USD 5 | **Field** | **Amount** | **Description** | | --------------------------------------------- | ---------- | ---------------------------------------------------- | | from\_amount | USD 100 | Amount entered by sender | | fee\_amount | USD 0 | Fee to be added after discount on fees (USD 5-USD 5) | | bonus\_amount | 0 | Bonus provided to the receiver | | Total amount deducted from sender’s account\* | USD 100 | from\_amount + fee\_amount - bonus\_amount | | exchange\_rate | 14 | Exchange rate including bonus FX (USD 1=GHS 14) | | Total amount received by the receiver | GHS 1400 | from\_amount\*exchange\_rate | \ **Sample Request** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount":100, "exchange_rate": 14, "to_amount":1400, "fee_amount": 0, "bonus_amount": 0, "note": "Sample Note", "to_currency":"GHS", "from_currency":"USD", "custom_purpose":"home", "purpose": "OTHER", "ip_address": "10.10.10.5", "from_fund_id": UUID, "funding_source_type": "CARD", "to":{ "id": UUID, "fund_id" : UUID, "payout_method":"BANK_DEPOSIT", "calculation_mode":"SENDER_AMOUNT" } }' ``` {% endtab %} {% endtabs %} # Business Payments Read for API integration recommendations for business payment use case. We consider all B2B and B2C transactions as business payments. Our business payments API include both transaction processing and delivery flow of business payments. Based on your requirements and agreement with Machnet, you may deliver the transactions yourself. Regardless, these are **external transactions** to external receivers (individuals or businesses) who may be residing in a country different from the sender. ## Integration Recommendations This section will guide you through the API endpoints for the business payment use case. Please note that these are recommendations for standard flow and can be customized as per your needs. ### 1. User Registration The first step is to [register the business user](/api-references/user/registration-1#register-a-user) in our system. Make sure to indicate business: *true* when you register a user. Users can only be registered from the country which has been enabled for you as per your agreement with Machnet. Fields outlined as mandatory in the user object are required during registration. ### 2. User KYB and Transaction Limits Upon registration, the user will have to provide basic information on the business and details of the business representative so that necessary KYB checks can be conducted. In order to run KYB on the sender, you will have to: 1. Know what [KYB information is required for the sender](/api-references/data-population/spec-sheet) 2. Collect and send the required [user](/api-references/user/user-kyc) and [business representative ](/api-references/user/business-representatives)information to Machnet 3. [Initiate verification process](/api-references/user/initiate-verification#post-users-user_id-kyc) User KYB is conducted using the following basic information. * Name of company * Type of company * Date of formation of the company * Registered address * Mailing address * Phone number * Email address * Nature of business * No. of employees * EIN Number * EIN Document Once you have submitted the information, [you also can check what KYB information has been provided by a user and its verification status](/api-references/user/get-verification-status). Each piece of information required for KYB and tier verification is referred to as a CIP tag and each CIP tag has its own verification status. Only when all CIP tags required for KYB verification (listed above) are verified will the KYB status of the user be verified. Additional information may be required based on the transaction amount and frequency. This information is outlined in your spec sheet and can also be obtained using [this API](/api-references/data-population/spec-sheet). Based on the information, you can submit the additional information collected from the user using the [Update user API](/api-references/user/user-kyc#update-kyc-information) or the [Update business representative API](/api-references/user/business-representatives/update-business-representatives). Each time new information is submitted, make sure to [initiate verification](/api-references/user/initiate-verification) on the user to ensure verification of all submitted information. ### 3. Add a Receive User All transactions must have an associated receiver. For business payments, the receiver could be an individual or a business. [To add a receiver, create a user with type "RECEIVE" and based on whether the receiver is an individual or business, you can set business as true or false.](/api-references/user/add-a-receive-user) The receive user's type (individual or business) and corridor of the transaction determines the required information of the receive user. These details are provided to you by the Machnet Team. You will have to collect all mandatory information and conditional information (if applicable), otherwise, the transaction may not be delivered to the receive user. We only support payout to bank accounts for business payments. Hence, along with the receive user details, the [receive user's account also has to be added](/api-references/funds/add-a-receive-account). The available banks and their details can be obtained using the [Banks API](/api-references/payout/get-banks). All banks which support business payments will have txn\_supported\_types as B2B and/or B2C. Funds will be directly deposited into the indicated receive user's account. ### 4. Add Funding Account Once the required transaction information has been collected, the user will then have to [link a funding source for the transaction](/api-references/funds/funding-account-widget). We support bank accounts and debit cards. These are added using a widget to ensure security. The sender can add a funding account and proceed to create a transaction as long as their KYB status is not UNVERIFIED and IN PROGRESS. ### 5. Additional information based on transaction You may need to collect additional information for each transaction such as an invoice for business payment or the purpose of the transaction. The additional information required may be based on the transaction amount or transaction corridor. Your spec sheet will contain all the additional transactional information that need to be collected. These need to be submitted during transaction creation. ### 6. Submit transaction You are now ready to [create the transaction](/api-references/transaction/create-1). Please note that only users with SEND capabilities can create transactions within the limits set in the CIP documents. The transaction limits available to a user are based on the submitted KYB information and their verification status. All transactions above the user's permitted limits and below the maximum transaction limit is placed on HOLD with the reason [*T004 Transaction Limit Exceeded*](/api-references/transaction/create-1#transaction-hold-reasons). In such cases, the user will need to provide additional information to increase their transaction limits. The verification status of those additional required fields (CIP tags) will be in REQUESTED status. Once this information is submitted, you will need to initiate KYC again for the user. If the submitted information is VERIFIED, the transaction will be forwarded for processing. If the transaction amount exceeds the maximum transaction limit set for a user of a Client, the transaction will be CANCELED. ### 7. Transaction Delivery Even though a transaction has been created, a transaction will not be forwarded for payout to the receive user unless you send a [delivery request](/api-references/transaction/transaction-delivery). You can choose to send a delivery request once the funds have been debited from the sender (transaction status: PROCESSED) to contain risks or beforehand to ensure faster payments. If you are delivering the transaction using your own payout network and NOT using our network, you will need to [update the delivery status](/api-references/transaction/transaction-delivery) on our system as well. # Individual Wallet Read for API integration recommendations for individual wallet use case Wallets allow you to hold funds of your users and the users are able to send those funds to other wallet holders within the system or externally to a receiver. ## Integration Recommendations This section will guide you through the API endpoints for the individual wallet use case which includes creating wallets, loading wallets, unloading wallets and creating transfers and transactions using wallets. Please note that these are recommendations for standard flow and can be customized as per your needs. ### 1. User Registration The first step in creating the user flow is to [register the user](/api-references/user/registration-1#register-a-user) in our system. Individual users need to be registered with the business field as false. Users can only be registered from the country which has been enabled for you as per your agreement with Machnet. Fields outlined as mandatory in the user object are required during registration. ### 2. User KYC Verification You will have to provide user information so that necessary KYC checks can be conducted on the sender. In order to run KYC on the sender, you will have to: 1. Know what [KYC information is required for the sender](/api-references/data-population/spec-sheet) 2. Collect and[ send the required information to Machnet](/api-references/user/user-kyc#update-kyc-information). 3. [Initiate KYC process for the user](/api-references/user/initiate-verification#post-users-user_id-kyc) User's KYC verification is conducted using the following information: * Name * Date of birth * Gender * Address * Email * Phone number Once you have submitted the information, [you check what KYC information has been provided by a user and its verification status](/api-references/user/get-verification-status). Each information required for KYC verification is referred to as a CIP tag and each CIP tag has their own verification status. Only when all CIP tags required for KYC verification (listed above) are verified will the KYC status of the user be verified. ### 3. User Tier Verification Users may be placed in different tiers based on the user information (CIP tags) they provide. The tiers dictate the following limits for each user: * Load limit: Annual, monthly and daily limit for transfers from linked bank/card to wallet * Unload limit: Annual, monthly and daily limit for transfers from wallet to linked bank/card * Transfer limit: Annual, monthly and daily limit for wallet to wallet transfers * External transaction limit: Annual, monthly and daily limit for external transactions * Hold limit: Amount of funds that can be held in a wallet at a certain time The tiers, their corresponding information requirements and eligibility limits are outlined in your spec sheet. Our APIs also provide the following: 1. [Current KYC status of the user](/api-references/user/get-verification-status) 2. [Current tier of the user ](/api-references/transaction-wallet/get-limits) 3. [Remaining transaction limits of the user in the current tier](/api-references/transaction-wallet/get-limits) 4. [Submitted CIP information and verification status of the user](/api-references/user/get-verification-status) 5. [Transaction limits per tier and corresponding CIP information for all users of the Client](/api-references/data-population/spec-sheet) You can submit the additional information of the user and update existing information collected from the user using the [Update KYC information API](/api-references/user/user-kyc#update-kyc-information). Each time new information is submitted, make sure to [initiate KYC](/api-references/user/initiate-verification) on the user to ensure verification of all submitted information. ### 4. Create a Wallet You can [create a designated wallet](/api-references/funds/create-a-wallet) for a VERIFIED user to hold funds. You can view the wallet details and balances using [this API.](/api-references/funds/get-wallet-details) Once the wallet status is VERIFIED, users can perform wallet related transfers and transactions. ### 5. Create Wallet Transfers and Transactions Users can create transfers from and to wallets and also use wallets as funding sources for external transactions. The following are the different types of [wallet transfers that users can create](/api-references/transaction-wallet/create-transfers). 1. Load: Adding funds to the wallet from a linked bank account or card. 2. Unload: Withdrawing funds from the wallet to a linked bank account or card. 3. Transfer: Send funds to another VERIFIED user's wallet. Along with this, users can [create external transactions using wallet as a funding source](/api-references/transaction/create-1). These are international remittance and business payments transactions. The user flow is the same as that outlined in the [Remittance](/use-cases/remittance) and [Business Payments](broken://pages/DAW945hokisNvmKTi4pV) use case section but in this particular case, the funding source will be the created wallet instead of a bank account or card. # Business Wallet Read for API integration recommendations for business wallet use case Business wallets allow business users to hold funds and send those funds to other wallet holders within the system or externally to a receiver. ## Integration Recommendations This section will guide you through the API endpoints for the business wallet use case such as creating wallets, loading wallets, unloading wallets and creating transfers and transactions using wallets. Please note that these are recommendations for standard flow and can be customized as per your needs. ### 1. User Registration The first step in creating the user flow is to [register the business user](/api-references/user/registration-1#register-a-user) in our system. Business users who want to enable business wallet need to be registered with the `business` field and `deposit_enabled` field both set to 'true'. Users can only be registered from the country which has been enabled for you as per your agreement with Machnet. Fields outlined as mandatory in the user object are required during registration. ### 2. User KYB and Declaration Upon registration, the user will have to provide basic information on the business and details of the business representative so that necessary KYB checks can be conducted. In order to run KYB on the sender, you will have to: 1. Know what [KYB information is required for the sender](/api-references/data-population/spec-sheet) 2. Collect and send the required [user](/api-references/user/user-kyc) and [business representative ](/api-references/user/business-representatives)information to Machnet 3. [Initiate verification process](/api-references/user/initiate-verification#post-users-user_id-kyc) 4. UBO Declaration User KYB is conducted using the following basic information. * Name of company * Type of company * Date of formation of the company * Registered address * Mailing address * Phone number * Email address * Nature of business * No. of employees * EIN Number * EIN Document * Business Representative Information * Full name * Address * DOB * Type * Email * Phone * Gender * Title * Ownership\_percentage, if beneficial owner * SSN if US individual or Passport no. if non-US individual * Copy of US government issued ID if US individual or foreign passport if non-US individual Once you have submitted the basic information, you will need to initiate KYB of the user. Once KYB has been initiated, you will need to collect the following declaration from the user. #### Declaration In order to complete verification of the user, the user must attest to the following statement and declare important information on the business. *I certify that the following information was submitted to Platform for all beneficial owners (holding 25% or more ownership) and controlling persons & executives:* * *US Person(s): SSN + US Government Issued Photo ID* * *Foreign Person(s): Tax Identification Number (if available) + Passport Number & Country of Issuance. In lieu of passport number, foreign persons may also provide an alien identification card number, or number and country of issuance of any other government issued photo ID evidencing nationality or residence.* The required details for the declaration can be found [here](/api-references/user/declaration/declaration-object). Since you will have to provide business representative IDs while using the [declaration API](/api-references/user/declaration/declaration), you will have to [add the required business representatives](/api-references/user/business-representatives/add-business-representatives) (account operator, beneficial owner, primary controller and compliance) before making a declaration request. Once you have submitted the basic information, [you check what KYC information has been provided by a user and its verification status](/api-references/user/get-verification-status). Each information required for KYC verification is referred to as a CIP tag and each CIP tag has their own verification status. Only when all CIP tags required for KYB verification (listed above) are verified and the declaration is completed will the KYB status of the user be verified. ### 3. User Tier Verification Users may be placed in different tiers based on the user information (CIP tags) they provide. The tiers dictate the following limits for each user: * Load limit: Annual, monthly and daily limit for transfers from linked bank/card to wallet * Unload limit: Annual, monthly and daily limit for transfers from wallet to linked bank/card * Transfer limit: Annual, monthly and daily limit for wallet to wallet transfers * External transaction limit: Annual, monthly and daily limit for external transactions * Hold limit: Amount of funds that can be held in a wallet at a certain time The tiers, their corresponding information requirements and eligible limits are outlined in your spec sheet. Our APIs also provide the following: 1. [Current KYB status of the user](/api-references/user/get-verification-status) 2. [Current tier of the user ](/api-references/transaction-wallet/get-limits) 3. [Remaining transaction limits of the user in the current tier](/api-references/transaction-wallet/get-limits) 4. [Submitted CIP information and verification status of the user](/api-references/user/get-verification-status) 5. [Transaction limits per tier and corresponding CIP information for all users of the Client](/api-references/data-population/spec-sheet) You can submit the additional information of the user and update existing information collected from the user using the [Update user API](/api-references/user/user-kyc#update-kyc-information). Each time new information is submitted, make sure to [initiate KYB](/api-references/user/initiate-verification) on the user to ensure verification of all submitted information. ### 4. Create a Wallet You can [create a designated wallet](/api-references/funds/create-a-wallet) for a VERIFIED user to hold funds. You can view the wallet details and balances using [this API.](/api-references/funds/get-wallet-details) Once the wallet status is VERIFIED, users can perform wallet related transfers and transactions. ### 5. Create Wallet Transfers and Transactions Users can create transfers from and to wallets and also use wallets as funding sources for external transactions. The following are the different types of [wallet transfers that users can create](/api-references/transaction-wallet/create-transfers). 1. Load: Adding funds to the wallet from a linked bank account or card. 2. Unload: Withdrawing funds from the wallet to a linked bank account or card. 3. Transfer: Send funds to another VERIFIED user's wallet. Along with this, users can [create external transactions using wallet as a funding source](/api-references/transaction/create-1). These are international business payments transactions. The user flow is the same as that outlined in the [Business Payments](broken://pages/DAW945hokisNvmKTi4pV) use case section but in this particular case, the funding source will be the created wallet instead of a bank account or card. # Payout Read for integration recommendations for payout use case Payout transactions are created specifically for you to disburse funds around the world. ### Integration Recommendations This section will guide you through the API endpoints for payout transactions. You can create your own flow based on your particular use case. ### 1. Client Registration While we set up your custom configurations based on your requirements, we will also create a unique user\_id for you. This user\_id allows us to identify transactions for your users and will have to be used while creating all payout transactions. ### 2. Collect all information required for a transaction Based on your specification sheet, you will need to collect information on the sender (from), receiver (to) and additional information based on transaction requirements. Additional information for each transaction may include invoices for business payments and the purpose of the transaction. This information needs to be submitted together during transaction creation. ### 3. Payout information We support different payout methods based on country and sender and receiver type. Detailed information on our network can be provided by our sales team. For Bank Deposit transactions, the available banks in our network and their details can be obtained using the [Banks API](/api-references/payout/get-banks). You need to provide bank details such as `to.bank_id` corresponding to the receiver's bank while creating a transaction. Please note that banks support specific `txn_supported_types` and in order for a transaction to be successfully deposited, the `txn_supported_types` must be in line with the sender and receiver type (Individual or Business). For Wallet transactions, all the available wallets in our network can be retrieved from the [Payers API](/api-references/payout/get-payers). The specific payer\_id corresponding to the receiver's wallet must be provided as `to.payer_id` during transaction creation. The receiver's wallets must be active for funds to be successfully deposited. For Cash Pickup, the user will have to select a payer location. The available payer details can be obtained using the [Payers API](/api-references/payout/get-payers). The associated payer\_id for the selected location will have to be used during transaction creation. ### 4. Submit transaction You are now ready to [create the transaction](/api-references/transaction-payout). You must specify`txn_type` as PAYOUT and use the provided Client specific `user_id` for all transactions. Once the transaction is created, the transaction is forwarded for payout through Machnet's payout network. The transaction status of PAYOUT transaction type will be NONE and the delivery status of the transaction will provide information on the payout status. Changes to the delivery status will be notified through [webhooks](/api-references/webhooks/events#delivery-events). Please note that all transaction created for payout will be deducted from your balance with Machnet and hence, the funding account for transactions do not need to be provided per transaction. # Data Population Read on obtaining services and specifications available for you. ## Overview Data on services enabled for you and your specification sheet can be obtained through APIs. You can sync this data in your systems to ensure that the information is up-to-date for you and your end users. # Spec Sheet You can retrieve your CIP as per your spec sheet using this API. The details are based on the approved products for you. It contains the following information: 1. Type of users configured for a Client (Individual and/or Business) 2. Tiers configured for each type of user 3. User's CIP information required for each tier 4. Transaction limit for each tier, differentiated by type of transaction (EXTERNAL, LOAD, UNLOAD, TRANSFER) 5. Wallet hold limit for each tier The transaction limits are segregated into daily limit, monthly limit and annual limit. These limits will reset based on UTC time and not at the time when the user creates the transaction. For example, * Daily limits for Mar 14 will be applicable from Mar 14 00:00:00 to 23:59:59 UTC and will reset on Mar 15 at 00:00:00 UTC * Monthly limits for March will be applicable from Mar 1 00:00:00 UTC to Mar 31 23:59:59 UTC * Annual limits for 2022 will be applicable from Jan 1 2022 00:00:00 UTC to Dec 31 2022 23:59:59 UTC The CIP tags for a tier level represent the user’s KYC information required in that tier level and is cummulative of all the CIP tags of that tier and all the tiers below it. For example, for Tier 3 user, all the CIP tags of Tier 1, Tier 2 and Tier 3 will be required. Please note that even if all the required KYC/KYB information for a specific limit is not collected and verified for a particular user, they can still conduct a transactions of that limit. However, the transaction will be placed on HOLD until the required information is submitted and verified. #### `GET /cip-info` {% tabs %} {% tab title="Request Sample" %} ``` curl --location --request GET '{{url}}/cip-info' \ --header 'X-Client-Id:{{client_id}} ' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "destinations": [ { "country": "Test Country", "individual": { "cip_infos": [ { "cip_tags": [ "ADDRESS_LINE1", "CITY", "COUNTRY", "ZIP_CODE", "GENDER", "STATE", "LAST_NAME", "EMAIL", "PHONE_NUMBER", "DATE_OF_BIRTH", "FIRST_NAME" ], "tier": 1, "transaction_limit": { "annual_limit": "10000", "daily_limit": "200", "monthly_limit": "5000" }, "type": "EXTERNAL" }, { "cip_tags": [ "ADDRESS_LINE1", "CITY", "COUNTRY", "ZIP_CODE", "GENDER", "STATE", "LAST_NAME", "EMAIL", "PHONE_NUMBER", "DATE_OF_BIRTH", "FIRST_NAME" ], "tier": 1, "transaction_limit": { "annual_limit": "10000", "daily_limit": "200", "monthly_limit": "5000", "max_wallet_hold_limit":5000 }, "type": "TRANSFER" }, { "cip_tags": [ "ADDRESS_LINE1", "CITY", "COUNTRY", "ZIP_CODE", "GENDER", "STATE", "LAST_NAME", "EMAIL", "PHONE_NUMBER", "DATE_OF_BIRTH", "FIRST_NAME" ], "tier": 1, "transaction_limit": { "annual_limit": "10000", "daily_limit": "10", "monthly_limit": "5000", "max_wallet_hold_limit":5000 }, "type": "UNLOAD" }, { "cip_tags": [ "ADDRESS_LINE1", "CITY", "COUNTRY", "ZIP_CODE", "GENDER", "STATE", "LAST_NAME", "EMAIL", "PHONE_NUMBER", "DATE_OF_BIRTH", "FIRST_NAME" ], "tier": 1, "transaction_limit": { "annual_limit": "10000", "daily_limit": "200", "monthly_limit": "5000", "max_wallet_hold_limit":5000 }, "type": "LOAD" }, { "cip_tags": [ "ID_NUMBER", "ID_ISSUING_AUTHORITY", "ID_DOC", "ID_EXPIRY_DATE" ], "tier": 2, "transaction_limit": { "annual_limit": "10000", "daily_limit": "2000", "monthly_limit": "5000", "max_wallet_hold_limit":5000 }, "type": "TRANSFER" }, { "cip_tags": [ "ID_NUMBER", "ID_ISSUING_AUTHORITY", "ID_DOC", "ID_EXPIRY_DATE" ], "tier": 2, "transaction_limit": { "annual_limit": "10000", "daily_limit": "2000", "monthly_limit": "5000", "max_wallet_hold_limit":5000 }, "type": "LOAD" }, { "cip_tags": [ "ID_NUMBER", "ID_ISSUING_AUTHORITY", "ID_DOC", "ID_EXPIRY_DATE" ], "tier": 2, "transaction_limit": { "annual_limit": "10000", "daily_limit": "2000", "monthly_limit": "5000", "max_wallet_hold_limit":5000 }, "type": "UNLOAD" }, { "cip_tags": [ "ID_NUMBER", "ID_ISSUING_AUTHORITY", "ID_DOC", "ID_EXPIRY_DATE" ], "tier": 2, "transaction_limit": { "annual_limit": "12000", "daily_limit": "500", "monthly_limit": "10000" }, "type": "EXTERNAL" }, { "cip_tags": [ "FULL_SSN" ], "tier": 3, "transaction_limit": { "annual_limit": "120000", "daily_limit": "10000", "monthly_limit": "10000" }, "type": "EXTERNAL" } ] } } ], "paging": { "page": 1, "page_size": 20, "total_count": 1 } } ``` {% endtab %} {% endtabs %} # Country Read on countries enabled for you The country APIs provide the list of available countries. **Get a list of all available countries** #### `GET /countries` {% tabs %} {% tab title="Request Sample" %} ``` curl --location --request GET '{{url}}/countries' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { { "currency": { "code": "MXN", "name": "Mexican peso", "symbol": "MXN" }, "name": "Mexico", "phone_code": "123", "three_char_code": "MEX", "two_char_code": "MX" }, { "currency": { "code": "INR", "name": "Indian Rupee", "symbol": "I" }, "name": "India", "phone_code": "91", "three_char_code": "IND", "two_char_code": "IN" } ] ``` {% endtab %} {% endtabs %} **Get country by code** #### `GET /countries`**/{{countryCode}}** {% tabs %} {% tab title="Details" %} | | | | | | ------------ | ------------ | -------- | -------------------------------- | | **Name** | **Required** | **Type** | **Description** | | countryCode | Yes | String | Two char ISO code of the country | | {% endtab %} | | | | {% tab title="Request Sample" %} ``` curl --location --request GET 'https://v4test.machpay.com/v4/countries/{{countryCode}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "currency": { "code": "INR", "name": "Indian Rupee", "symbol": "I" }, "name": "India", "phone_code": "91", "three_char_code": "IND", "two_char_code": "IN" } ``` {% endtab %} {% endtabs %} # States Read on populating states enabled for you The States API provides a list of all states of the countries enabled for you. ### **Get states in a country** #### `GET /countries/{{countryCode}}/states` {% tabs %} {% tab title="Details" %} | | | | | | ------------ | ------------ | -------- | -------------------------------- | | **Name** | **Required** | **Type** | **Description** | | countryCode | Yes | String | Two char ISO code of the country | | {% endtab %} | | | | {% tab title="Request Sample" %} ``` curl --location --request GET '{{url}}/{{countryCode}}/states' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` [ { "code": "CA", "country": "US", "name": "California" } ] ``` {% endtab %} {% endtabs %} ### **Get states by code** #### `GET /countries/{{countryCode}}/states`**/{{stateCode}}** {% tabs %} {% tab title="Details" %} | | | | | | ------------ | ------------ | -------- | -------------------------------- | | **Name** | **Required** | **Type** | **Description** | | countryCode | Yes | String | Two char ISO code of the country | | stateCode | Yes | String | State code | | {% endtab %} | | | | {% tab title="Request Sample" %} ``` curl --location --request GET 'https://v4test.machpay.com/v4/countries/{{countryCode}}/states/{{stateCode}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "code": "CA", "country": "US", "name": "California" } ``` {% endtab %} {% endtabs %} # Settlement Rates Read on obtaining rates at which the transaction will be settled While you can set the exchange rate for a particular transaction while creating the transaction, this API will provide you with the current settlement rates. Settlement rates may differ based on sending currency, receiving country, receiving currency, and payout method. **`GET /settlement-rates`** {% tabs %} {% tab title="Details" %} **Query Parameters** | | | | | | --------------------- | ------------ | -------- | ------------------------------------------------------ | | **Name** | **Required** | **Type** | **Description** | | source\_currency | No | String | Sending currency code | | destination\_currency | No | String | Receiving currency code | | destination\_country | No | String | Two char ISO code of the receiving country | | payout\_method | No | String | CASH\_PICKUP, BANK\_DEPOSIT, WALLET, or HOME\_DELIVERY | | {% endtab %} | | | | {% tab title="Sample Request" %} ``` curl --location --request GET '{{url}}/settlement-rates?destination_currency={{currencyCode}}&source_currency={{currencyCode}}&destination_country={{countryCode}}&payout_method=CASH_PICKUP' --header 'X-Client-Id: {{clientId}}' --header 'X-Client-Secret: {{clientSecret}}' --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Sample Response" %} ``` [ { "created_at": "2022-03-22 12:00:05", "destination_country": "GH", "destination_currency": "GHS", "payout_method": "CASH_PICKUP", "settlement_rate": "5.6794", "source_currency": "USD" } ] ``` {% endtab %} {% endtabs %} # User Read on creating and managing users in our system ## Overview In order for your users to use your services, they will have to be registered in our system and undergo KYC/KYB checks. The API endpoints in this section will allow you to create these users with SEND capabilities. Users at the receiving end will also need to be created in the system using the appropriate APIs. All RECEIVE users will be linked to their specific SEND users. # User Object Read about user object details {% tabs %} {% tab title="Details" %} | **Field** | **Required** | **Type** | **Description** | | ----------------------------------------- | --------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | mobile\_phone | Yes | Numeric | 10-15 digits phone number | | email | Yes | String | Email address | | first\_name | Yes | String | First name or name of the business. | | middle\_name | No | String | Middle name | | last\_name | Yes, if individual | String | Family name | | gender | Yes, if individual | String | Male, female, other. *Not mandatory for user registration but needed before user KYC is initiated.* | | date\_of\_birth | Yes | String | Birth date of individual or Day of formation for business in yyyy-MM-dd format. *Not mandatory for user registration but needs to be collected before user KYC/KYB is initiated.* | | business | Yes | Boolean | By default false. Required to send True if user is a business. | | business\_type | Yes, if Business | Category |

Example : LLC, PARTNERSHIP, SOLE-PROPRIETORSHIP, etc.

Note : Details provided below.

| | user\_scope | Yes, if Business | Category |

Nature of business. Not mandatory for registration but needed before user KYC/KYB is initiated.

Note : Details below

| | address\_line1 | Yes | String | Address of individual/business. *Not mandatory for registration but needed before user KYC/KYB is initiated.* | | address\_line2 | No | String | Street address of the individual/business | | city | Yes | String | City of residence of the individual or registered city of the business. | | state | Yes | String | 2-letter ISO code of the user's state. | | country | Yes | String | 2-letter ISO code of user's country. | | zipcode | Yes | String | Zip code of the user's address. | | mailing\_address | Yes, if business | String | Company's mailing address. Address\_line1, address\_line2, city, state, country & zipcode. *Not mandatory for registration but needed before user KYC/KYB is initiated.* | | status | In response | Category |

KYC/KYB Status of the user. For unverified user, KYC/KYB is not done.

Enumerated value: UNVERIFIED, VERIFIED, REVIEW\_PENDING, SUSPENDED, IN\_PROGRESS, RETRY.

| | ip\_address | Yes | String | IP of the user. | | occupation | Conditional | String | User’s occupation. *This field may be required for KYC/KYB based on your spec sheet.* | | type | Yes | Category | Enumerated Value : ‘SEND’ , ‘RECEIVE’ | | created\_at | In Response | String | Date and time of user’s registration | | company\_website | Yes, if business with `deposit_enabled`: true | String |

Company's offical website. This field is not mandatory for user registration but needs to be collected before user KYB is initiated.

For other business users, this field may be required for KYB based on your spec sheet.

| | number\_of\_employee | Yes, if business | Category | Enum Values: ‘LESS\_THAN\_25’, ‘BETWEEN\_25\_TO\_50’, ‘MORE\_THAN\_50’. *This field is not mandatory for user registration but needs to be collected before user KYB is initiated.* | | **physical\_documents** | Yes, if business with `deposit_enabled`: true | **Object** | **Copy of a document. *****This field may be required for KYC/KYB based on your spec sheet.*** | | physical\_documents.document\_type | Yes, if physical\_document is required | String | Enumerated value. Note: Details provided below. | | physical\_documents.document\_value | Yes, if physical\_document is required | String | Value of the document. Documents must be encoded Base64 before being uploaded to our system. | | physical\_documents.document\_value\_back | Conditional | String | Value of the rear side of the document. Documents must be encoded Base64 before being uploaded to our system. | | physical\_documents.country | Conditional | String | 2-letter ISO code of the user’s country. | | physical\_documents.state | Conditional | String | 2-letter ISO code of the user’s state. | | physical\_documents.expiry\_date | Conditional | String | Date of expiry of the document. | | **virtual\_documents** | Yes, if business with `deposit_enabled`: true | **Object** | **Identification document's information. *****This field may be required for KYC/KYB based on your spec sheet.*** | | virtual\_documents.document\_type | Yes, if virtual\_document is required | String | Enumerated value. Note: Details provided below. | | virtual\_documents.document\_value | Yes, if virtual\_document is required | String | Value of the ID number. Example : Passport Number. | | virtual\_documents.issue\_date | Conditional | String | Date of issue of the document. | | virtual\_documents.expiry\_date | Conditional | String | Date of expiry of the document. | | virtual\_documents.id\_issuing\_authority | Conditional | String | ID issuing authority of the document. Please provide State if ID is DRIVING LICENSE or STATE ID and country if PASSPORT. | | virtual\_documents.country | Conditional | String | 2-letter ISO code of the document issued country. | | virtual\_documents.state | Conditional | String | 2-letter ISO code of the document issued state. | | **company\_details** | Conditional | **Object** | **Details of the company. *****This may be required for KYC based on your spec sheet.*** | | company\_details.company\_name | Yes, if company details is required | String | Name of the company where the individual user is employed. | | company\_details.address | Yes, if company details is required | String | Address of the company where the individual user is employed. | | company\_details.phone\_number | Yes, if company details is required | String | Phone number of the company where the individual user is employed. | | number\_of\_transaction\_per\_month | Conditional | Numeric | Estimate value of user's transactions per month. *This field may be required for KYB based on your spec sheet.* | | transaction\_frequency | Conditional | Category | Enum Values: DAILY, WEEKLY, BI\_WEEKLY, MONTHLY. *This field may be required for KYB based on your spec sheet.* | {% hint style="info" %} Please note that although fields may be optional during registration, certain fields may be mandatory for KYC/KYB. The mandatory fields for KYC/KYB will be outlined in your specification sheet. {% endhint %}

User Scope Enumerated Values

NOT_KNOWN("Not Known"),
AIRPORT("Airport"),
ARTS_ENTERTAINMENT("Arts & Entertainment"),
AUTOMOTIVE("Automotive"),
BANK("Bank & Financial Services"),
BAR("Bar"),
BOOK_STORE("Book Store"),
BUSINESS_SERVICE("Business Services"),
RELIGIOUS_ORGANIZATION("Religious Organization"),
CLUB("Club"),
COMMUNITY_GOVERNMENT("Community/Government"),
CONCERT_VENUE("Concert Venue"),
DOCTOR("Doctor"),
EVENT_PLANNING("Event Planning/Event Services"),
FOOD_GROCERY("Food/Grocery"),
HEALTH_MEDICAL("Health/Medical/Pharmacy"),
HOME_IMPROVEMENT("Home Improvement"),
HOSPITAL_CLINIC("Hospital/Clinic"),
HOTEL("Hotel"),
LANDMARK("Landmark"),
LAWYER("Lawyer"),
LIBRARY("Library"),
LOCAL_BUSINESS("Local Business"),
MUSEUM_ART_GALLERY("Museum/Art Gallery"),
OUTDOOR_SPORTING_GOODS("Outdoor Gear/Sporting Goods"),
PET_SERVICES("Pet Services"),
PROFESSIONAL_SERVICES("Professional Services"),
REAL_ESTATE("Real Estate"),
RESTAURANT_CAFE("Restaurant/Cafe"),
SCHOOL("School"),
SHOPPING_RETAIL("Shopping/Retail"),
SPORTS_VENUE("Sports Venue"),
TOURS("Tours/Sightseeing"),
TRANSPORTATION("Transportation"),
UNIVERSITY("University"),
AEROSPACE_DEFENCE("Aerospace/Defense"),
AUTOMOBILE_PARTS("Automobiles and Parts"),
FINANCIAL_INSTITUTION("Bank/Financial Institution"),
BIOTECHNOLOGY("Biotechnology"),
COMPUTER_TECHNOLOGY("Computers/Technology"),
EDUCATION("Elementary School"),
CONSTRUCTION("Engineering/Construction"),
AGRICULTURE("Farming/Agriculture"),
FOOD_BEVERAGES("Food/Beverages"),
GOVERNMENT_ORGANIZATION("Government Organization"),
INDUSTRIALS("Industrials"),
INSURANCE_COMPANY("Insurance Company"),
MEDIA("Media/News/Publishing"),
MINING("Mining/Materials"),
NON_GOVERNMENTAL_ORGANIZATION("Non-Governmental Organization (NGO)"),
ORGANIZATION("Organization"),
POLITICAL_ORGANIZATION("Political Organization"),
POLITICAL_PARTY("Political Party"),
TELECOMMUNICATION("Telecommunication"),
TRANSPORT("Transport/Freight"),
TRAVEL_LEISURE("Travel/Leisure")

Business Type Enumerated Values 

    NOT_KNOWN("Not Known"),
    LLC("LLC"),
    ASSOCIATION("ASSOCIATION"),
    CORP("CORP"),
    PARTNERSHIP("PARTNERSHIP"),
    SOLE_PROPRIETORSHIP("SOLE-PROPRIETORSHIP"),
    TRUST("TRUST"),
    VENDOR("VENDOR"),
    ESTATE("ESTATE"),
    IRA("IRA")

Physical Document Type Enumerated Values

Note: File size must not exceed 2 MB.

Virtual Document Type Enumerated Values

PASSPORT
DRIVING_LICENCE
STATE_ID
SSN
EIN_NUMBER
| | | | ------------------------------ | ---------------------- | | PASSPORT | jpg, jpeg, and png | | DRIVING\_LICENCE | jpg, jpeg, and png | | STATE\_ID | jpg, jpeg, and png | | BANK\_STATEMENT | jpg, jpeg, png and pdf | | PAY\_SLIP | jpg, jpeg, png and pdf | | TAX\_RETURN\_FILES | jpg, jpeg, png and pdf | | AUDITED\_FINANCIALS | jpg, jpeg, png and pdf | | EIN | jpg, jpeg, png and pdf | | CERTIFICATE\_OF\_INCORPORATION | jpg, jpeg, png and pdf | {% hint style="info" %} If your specification sheet requires you to submit source of funds for a user, the document will have to be submitted as a physical document with the specific type outlined in the 'document\_type' field. {% endhint %} {% endtab %} {% endtabs %} # User Verification The User identification and verification policies and procedures of the program are designed to: * Ensure adherence with the user identification and KYC policy of FI partners and various State, Federal and International regulators governing the provision of the services. * Ensure adherence with all compliance requirements of FI partners and State/Federal/International regulators. * Promote safe and secured business practices and minimize the risk of the services from being misutilized for any fraud, money laundering and other illegal activities. * Help monitor and report suspicious activities. ### User Verification and Transaction Limits Our verification processes are designed in line with the compliance policies of our FI partners including the requirements of the Banking Secrecy Act (BSA) and all other State, Federal and International Money Transfer Regulations. This requires collection of certain information from users during the registration based on the amount and volume of transactions. Accordingly, we have devised a Tier based verification program which governs the transaction limits and KYC/KYB requirements for each tier. {% hint style="info" %} Your Specification Sheet, provided by Machnet, will include details of the Transaction limits and KYC/KYB requirements applicable for your users. {% endhint %} User Verification is divided into KYC/KYB verification and Tier verification. Information required for KYC/KYB and tier verification is referred to as CIP tags. Each user has a KYC/KYB verification status and each field corresponding to the required CIP tag also has its own verification status. Only when all CIP information required for KYC/KYB verification (listed below) are verified will the KYC status of the user be verified. ### **KYC/KYB Verification** If the user is an individual, the following basic information will be required to perform Know Your Customer (KYC) verification checks. * Name * Date of birth * Gender * Address * Email * Phone number If the user is a business, the following basic information will be required to perform Know Your Business (KYB) verification checks. * Name of company * Type of company * Date of formation of the company * Registered address * Mailing address * Phone number * Email address * Nature of business * No. of employees * EIN Number * EIN Document * Certificate of Incorporation (if `deposit_enabled`: true) * Company Website (if `deposit_enabled`: true) * Business Representative Information (if `deposit_enabled`: true) * Full name * Address * DOB * Email * Phone * Gender * Title * Ownership\_percentage (if beneficial owner) * Business representative type * SSN if US individual * Passport no. if non-US individual * Copy of US government issued ID (Passport, driving license or state ID) if US individual * Copy of foreign passport if non-US individual {% hint style="info" %} The Platform requires the user to complete user verification for any transaction of the user to be processed and paid out. Any user whose verification is pending may however be allowed to perform other actions in the Platform, unless they are “Suspended”. {% endhint %} ### **Tier Verification** While basic information is required for KYC/KYB verification, additional CIP information may need to be collected and verified for the user to be able to transact. The required information for each tier and their corresponding transaction limits are outlined in your Specification Sheet. While the user may be able to create a transaction without submission and verification of the required tier information, the transaction will not be processed and paid out until the required information is submitted and verified. # Identification Documents In accordance with the specification sheet, a user may be required to provide a valid ID for the purpose of their verification or to increase their transaction limits. The user will be required to provide information such as the ID type, ID number, Expiry Date along with a copy of ID. You shall ensure that the ID provided by the user is: * an acceptable type of ID, * a valid ID, * according to ID Criteria outlined below {% hint style="info" %} If document information is required, you will need to pass the information as a VIRTUAL DOCUMENT. If document copy is required, you will need to pass the document as a PHYSICAL DOCUMENT. Depending on the ID type, an image of the front and back of the ID document may be required. The details on the requirements are outlined in your specification sheet. {% endhint %} #### Acceptable ID Types In the case of individual users, an acceptable type of ID is one or more of the following (unexpired) IDs: * US Federal Government issued Passport * US Federal or State Government issued ID * State Government issued Driver’s License * Passport issued by Foreign Government with valid isa or I-94 #### Examples for Invalid ID * The ID has holes punched in it. * The ID is stamped. * The ID is expired. #### ID Criteria The ID copies uploaded by users are recommended to meet the following criteria to improve accuracy: * The image should be steady. * Blurry images will not be verified. * The ID should occupy most of the image. * The ID and text should be aligned properly- Photo image of the ID should be taken on a flat surface. * The ID should have a Plain background. * Name on the ID should match the Name and DOB provided by the user during signup. * The ID should be uploaded only in .jpeg or .jpg format. * Photo image of the ID should be in full color (no black and white images accepted). * All four (4) corners of the ID should be visible in the uploaded copy. * The uploaded copy should not have any shadow or lighting effects such as Flash. * All the details on the ID, for example, photo of the user, expiry date, etc. should be clearly visible. * The uploaded copy or any part of it should be human and machine readable. * Min resolution \~1200 pixels, minor axis. * Good natural lighting (average pixel intensity \~150). * We recommend a maximum file size of 2 MB (most high-quality JPG are around 1 MB). **Note:** Users should be informed of the above ID criteria. # User Verification Status The KYC verification process is an automated process conducted on a real time basis. The KYB verification process may require additional time based on our service level agreement. During this verification process, the user is placed under various KYC Statuses as described below: #### Unverified A user is placed in `Unverified` status until they submit their KYC information for verification. #### Retry A user is placed in `Retry` status when the user is not verified automatically in the first instance and new information and/or documentation is required. Once the information/documentation is provided, users can move to another KYC status or stay in ‘Retry’ status if additional information/documentation is required again. If the user cannot be ‘Verified’ or ‘Suspended’ after multiple retries, the user will be moved to ‘Review Pending’ status for review by Machnet’s compliance team. #### In Progress A user has submitted their KYC information and their verification is in process. #### Review Pending A user is placed in `Review Pending` status if the user is not verified after multiple `Retry` statuses or if the information requires review by Machnet’s Compliance team. Machnet shall inform the Client regarding any further information and/or document that will be required to verify the user by placing the user under `Retry`. Machnet may also verify or suspend the user based on their submitted information. #### Verified User’s KYC has been successfully `verified`. #### Suspended A user in `Suspended` status is not allowed to conduct any activity in the system. A user may be placed in `Suspended` status for one or more of the following reasons: * The Platform identifies anything suspicious during the Verification process of the user. * Identification of any AML, fraud or compliance risk with the user (whether or not the user is a verified user). * Any discrepancy in the KYC documents and information provided by the user. # CIP Information Status Information required for user verification (KYC/KYB and tier) are considered CIP info in the Platform. Each required CIP information corresponds to a user object field. The user object fields has a specific verification status which determines the KYC status and transaction limits of the user. #### Verified The information/document has be successfully verified. #### Failed The information/document could not be verified. Please review our Dashboard or contact Machnet Support for additional details. #### Reviewing The information/document is currently being reviewed for verification. #### Submit The information/document has been successfully submitted and will be reviewed for verification. #### Requested The information/document has been requested. Client must collect the requested fields from the user, update the user with the information and initiate verification. The verification status of the user's CIP information will be updated based on the results. # Receive User Object Read on how to add a receive user {% tabs %} {% tab title="Details" %} | **Field** | **Required** | **Type** | **Description** | | ----------------------------------------- | -------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | mobile\_phone | Yes | Alpha-numeric | 10 digits mobile number of the individual or 10-15 digits phone number of the business. | | email | No | String | Email address of the user or business. *This field may be required based on your spec sheet.* | | first\_name | Yes | String | First name of the individual or name of the business. | | middle\_name | No | String | Middle name of the individual | | last\_name | Yes, if individual | String | Family name of the individual | | gender | Conditional | String | Male, female, other. *This field may be required based on your spec sheet.* | | date\_of\_birth | Conditional | String | Birth date of individual or Day of formation for business in yyyy-MM-dd format. *This field may be required based on your spec sheet.* | | business | Yes | Boolean | By default false. True if user is a business. | | address\_line1 | Yes, if business receive user | String | Street address of the individual or registered address of the business. | | address\_line2 | No | String | Street address of the individual or registered address of the business. | | city | Yes | String | City of residence of the individual or registered city of the business. | | state | Yes, if business receive user | String | 2-letter ISO code of the user's state. | | country | Yes | String | 2-letter ISO code of user's country. | | zipcode | Yes, if business receive user | String | Zip code of the user's address. | | occupation | Conditional | String | User’s occupation. *This field may be required based on your spec sheet.* | | type | Yes | Category | Enumerated Value : ‘SEND’ , ‘RECEIVE’ | | created\_at | In Response | String | Date and time of user’s registration | | **physical\_documents** | Conditional | **Object** | **Copy of a document. *****This field may be required based on your spec sheet.*** | | physical\_documents.document\_type | Yes, if physical\_document is required | String | Enumerated value. Note: Details provided below. | | physical\_documents.document\_value | Yes, if physical\_document is required | String | Value of the document. Documents must be encoded Base64 before being uploaded to our system. | | physical\_documents.document\_value\_back | Conditional | String | Value of the rear side of the document. Documents must be encoded Base64 before being uploaded to our system. | | physical\_documents.country | Conditional | String | 2-letter ISO code of the user’s country. | | physical\_documents.state | Conditional | String | 2-letter ISO code of the user’s state. | | physical\_documents.expiry\_date | Conditional | String | Expiry date of document | | **virtual\_documents** | Conditional | **Object** | **Identification document's information. *****This field may be required based on your spec sheet.*** | | virtual\_documents.document\_type | Yes, if virtual\_document is required | String | Enumerated value. Note: Details provided below. | | virtual\_documents.document\_value | Yes, if virtual\_document is required | String | Value of the ID number. Example : Passport Number. | | virtual\_documents.issue\_date | Conditional | String | Date of issue of the document. | | virtual\_documents.expiry\_date | Conditional | String | Date of expiry of the document. | | virtual\_documents.id\_issuing\_authority | Conditional | String | ID issuing authority of the document. Please provide State if ID is DRIVING LICENSE or STATE ID and country if PASSPORT. | | virtual\_documents.country | Conditional | String | 2-letter ISO code of the document issued country. | | virtual\_documents.state | Conditional | String | 2-letter ISO code of the document issued state. | | user\_relationship | Conditional | String | Enumerated Value. Details provided below. *This field may be required based on your spec sheet.* | | send\_user\_id | In Response | UUID | The ID of the send user who is registering the receive user to make a transfer. | #### User Relationship Enumerated Values ``` AUNT("Aunt"), BROTHER("Brother"), BROTHER_IN_LAW("Brother in Law"), COUSIN("Cousin"), DAUGHTER("Daughter"), FATHER("Father"), FATHER_IN_LAW("Father in Law"), FRIENDS("Friends"), GRANDFATHER("Grand Father"), GRANDMOTHER("Grand Mother"), HUSBAND("Husband"), MOTHER("Mother"), MOTHER_IN_LAW("Mother in law"), NEPHEW("Nephew"), NIECE("Niece"), SELF("Self"), SISTER("Sister"), SISTER_IN_LAW("Sister in Law"), SON("Son"), UNCLE("Uncle"), WIFE("Wife"), OTHERS("Others") ``` **Physical Document Type Enumerated Values** ``` PASSPORT DRIVING_LICENCE STATE_ID ``` **Virtual Document Type Enumerated Values** ``` PASSPORT DRIVING_LICENCE STATE_ID EIN_NUMBER ``` {% hint style="info" %} Please note that certain receive user information may be required based on the receiving country even though it may be outlined as optional in the API docs. Contact Machnet for a list of all the mandatory receive user information for your specific corridor. {% endhint %} {% endtab %} {% endtabs %} # Register a User Read on how to create SEND users in our system This endpoint creates a new user account for both individual and business users with just the user's basic information. If you want to enable sending capabilities to a user, you need to specify it with "type": "SEND" in the request. Only users in originating corridors enabled for you can be created with send capabilities. A unique ID will be generated as a response. Please note the additional parameters for the Business user compared to an individual user. More details on the request sample. #### `POST /users` {% tabs %} {% tab title="Request Sample" %} **Individual User** ``` curl --location -g --request POST '{{url}}/users' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "Tenzin", "last_name": "Norgay", "email": "norgayt@test.com", "gender": "female", "date_of_birth": "2000-01-01", "address_line1": "500 8 El Camino Real Santa Clara", "mobile_phone": "9879879870", "city": "Santa Clara", "zipcode": "95053", "state": "CA", "country": "US", "ip_address": "73.85.79.9", "type": "SEND", "physical_documents": [ { "document_value": "data:image/jpg;base64,SUQsasasasas909090==", "document_type": "STATE_ID", "country": "US", "expiry_date": "2025-03-09", "state": "CA" } ], "virtual_documents": [ { "document_value": "111111111", "document_type": "PASSPORT", "expiry_date": "2025-03-09", "id_issuing_authority": "CA", "country": "US", "state": "CA" }, { "document_value": "111111111", "document_type": "SSN", "expiry_date": "2025-03-09", "id_issuing_authority": "CA", "country": "US", "state": "CA" } ] }' ``` **Business user** ``` curl --location -g --request POST '{{url}}/users' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "Machnet Technologies Inc", "mobile_phone": "2222222222", "address_line1": "500 8 El Camino Real Santa Clara", "city": "Santa Clara", "zipcode": "95053", "state": "CA", "country": "US", "email": "example@mail.com", "ip_address": "10.0.10.5", "date_of_birth": "1995-01-01", "business": true, "business_type": "LLC", "user_scope": "COMPUTER_TECHNOLOGY", "company_website": "www.example.com", "number_of_employee": "BETWEEN_25_TO_50", "type": "SEND", "mailing_address": { "country": "US", "city": "Santa Clara", "address_line1": "500 8 El Camino Real Santa Clara", "zipcode": "95053", "state": "CA", "address_line2": null }, "physical_documents": [ { "document_value": "data:application/pdf;base64,SUQs==", "document_type": "EIN" "expiry_date": "2025-03-09", "state": "CA" } ], "virtual_documents": [ { "document_value": "823452222", "document_type": "EIN_NUMBER" "expiry_date": "2025-03-09", "id_issuing_authority": "CA", "state": "CA", } ] }' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "address_line1": "500 8 El Camino Real Santa Clara", "city": "Santa Clara", "country": "US", "created_at": "2022-03-11T04:32:24.48354", "date_of_birth": "2000-01-01", "email": "norgayt@test.com", "first_name": "Tenzin", "gender": "female", "id": "022ea509-a4ab-4bb9-ad98-305c08bd2b42", "ip_address": "73.85.79.9", "last_name": "Norgay", "mobile_phone": "9879879870", "state": "CA", "status": "UNVERIFIED", "zipcode": "95053", "business": false, "type": "SEND", "physical_documents": [ { "id": {{UUID}}, "document_type": "STATE_ID", "country": "US", "expiry_date": "2025-03-09", "state": "CA" } ], "virtual_documents": [ { "document_value": "111111111", "id": {{UUID}}, "document_type": "PASSPORT", "expiry_date": "2025-03-09", "id_issuing_authority": "CA", "country": "US", "state": "CA" }, { "document_value": "111111111", "id": {{UUID}}, "document_type": "SSN", "expiry_date": "2025-03-09", "id_issuing_authority": "CA", "country": "US", "state": "CA" } ] } ``` **Business User** ``` { "address_line1": "500 8 El Camino Real Santa Clara", "city": "Santa Clara", "company_website": "www.example.com", "country": "US", "created_at": "2022-04-22T02:21:23.084565", "date_of_birth": "1995-01-01", "email": "example@mail.com", "first_name": "Machnet Technologies Inc", "id": {{UUID}}, "ip_address": "10.0.10.5", "mailing_address": { "address_line1": "500 8 El Camino Real Santa Clara", "city": "Santa Clara", "country": "US", "state": "CA", "zipcode": "95053" }, "mobile_phone": "2222222222", "number_of_employee": "BETWEEN_25_TO_50", "physical_documents": [ { "document_type": "EIN", "id": {{UUID}}, "expiry_date": "2025-03-09", "state": "CA" } ], "state": "CA", "status": "UNVERIFIED", "user_scope": "COMPUTER_TECHNOLOGY", "virtual_documents": [ { "document_type": "EIN_NUMBER", "document_value": "2222", "id": {{UUID}}, "expiry_date": "2025-03-09", "id_issuing_authority": "CA", "state": "CA", } ], "zipcode": "95053", "business": true, "business_type": "LLC", "type": "SEND" } ``` {% endtab %} {% endtabs %} # Update User Read on collecting KYC information and running KYC checks on SEND users This API allows you to update the user information. You can provide all the required user information at once. You can also update the user information partially by using this API multiple times as required. Details on what fields can be updated when a user is verified and not verified are provided below. #### `PATCH /users/{{user_id}}` {% tabs %} {% tab title="Individual" %} **Updatable fields for send user (individual)** | **Fields** | **User is verified** | **User is not verified** | **Additional details** | | ------------------- | -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------- | | first\_name | No | Yes | | | middle\_name | No | Yes | | | last\_name | No | Yes | | | mobile\_phone | Yes | Yes | | | email | No | Yes | | | address\_line1 | Yes | Yes | | | address\_line2 | Yes | Yes | | | city | Yes | Yes | | | state | Yes | Yes | | | country | No | No | | | zipcode | Yes | Yes | | | date\_of\_birth | No | Yes | | | gender | No | Yes | | | user\_scope | No | Yes | | | occupation | Yes | Yes | | | type | No | No | | | physical\_documents | Yes | Yes | Updating physical\_document object will add a new copy of the document and archive the older one. | | virtual\_documents | Conditional | Yes | SSN is not updatable once user is verified. | | company\_details | Yes | Yes | | | {% endtab %} | | | | {% tab title="Business" %} **Updatable fields for send user (business)** | **Fields** | **User is verified** | **User is not verified** | **Additional details** | | -------------------------------------------------------------------------------- | -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ | | first\_name | No | Yes | | | mobile\_phone | Yes | Yes | | | email | Yes | Yes | | | address\_line1 | Yes | Yes | | | address\_line2 | Yes | Yes | | | city | Yes | Yes | | | state | Yes | Yes | | | country | No | No | | | zipcode | Yes | Yes | | | date\_of\_birth | No | Yes | | | business | No | No | | | business\_type | No | Yes | | | user\_scope | No | Yes | | | company\_website | Yes | Yes | | | number\_of\_employee | Yes | Yes | | | mailing\_address (address\_line1, address\_line2, city, state, country, zipcode) | Yes | Yes | | | virtual\_documents | No | Yes | | | physical\_documents | Conditional | Yes | Physical documents of type EIN and CERTIFICATION\_OF\_INCORPORATION cannot be updated once user is verified. | | user\_relationship | No | No | | | number\_of\_transaction\_per\_month | Yes | Yes | | | transaction\_frequency | Yes | Yes | | {% endtab %} {% tab title="Request Sample" %} **Individual User** ``` curl --location -g --request PATCH '{{url}}/users/{{user_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name":"Tenzin", "middle_name":"", "last_name":"Norgay", "date_of_birth":"2000-01-01", "email":"norgay@test.com", "gender":"female", "id":"f45680e1-014d-42c7-be86-3b2899e911c3", "ip_address":"10.0.0.1", "mobile_phone":"2106603032", "address_line1":"500 8 El Camino Real Santa Clara", "city":"Santa Clara", "state":"CA", "country":"US", "zipcode":"95053", "occupation":"Banker", "company_details":{ "company_name":"ACME", "address":"123 address st", "phone_number":"222222222" }, "physical_documents":[ { "document_value":"data:image/jpg;base64,SUQs==", "document_value_back":"data:image/jpg;base64,SUQs==", "country":"US", "document_type":"DRIVING_LICENCE", "state":"CA" }, { "document_value":"data:image/jpg;base64,SUQs==", "document_type":"BANK_STATEMENT", } ], "virtual_documents":[ { "document_value":"1111111111", "document_type":"DRIVING_LICENCE", "expiry_date":"2025-03-09", "id_issuing_authority":"CA", "country":"US", "state":"CA" }, { "document_value":"111111112", "document_type":"SSN", "country":"US", "state":"CA" } ] }' ``` **Business User** ``` curl --location -g --request PATCH '{{url}}/users/{{user_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "number_of_transaction_per_month": "122", "transaction_frequency": "WEEKLY", "physical_documents": [ { "document_value": "data:application/pdf;base64,SUQs==", "document_type": "CERTIFICATE_OF_INCORPORATION" }, { "document_value":"data:image/jpg;base64,SUQs==", "document_type":"AUDITED_FINANCIALS" } ] }' ``` {% endtab %} {% tab title="Response Sample" %} **Individual User** ``` { "address_line1": "500 8 El Camino Real Santa Clara", "city": "Santa Clara", "company_details": { "address": "123 address st", "company_name": "ACME", "phone_number": "222222222" }, "country": "US", "created_at": "2022-03-29T15:59:03.699517", "date_of_birth": "2000-01-01", "email": "norgay@test.com", "first_name": "Tenzin", "gender": "female", "id": "f45680e1-014d-42c7-be86-3b2899e911c3", "ip_address": "10.0.0.1", "last_name": "Norgay", "middle_name": "", "mobile_phone": "2106603032", "occupation": "Banker", "physical_documents": [ { "country": "US", "document_type": "DRIVING_LICENCE", "id": "d20dd857-7dc0-4abc-879f-fcfb15f4423d", "state": "CA" }, { "document_type": "BANK_STATEMENT", "id": "9f57c7c9-ffa5-4e88-a28a-af3af1232a46" } ], "state": "CA", "status": "UNVERIFIED", "user_scope": "ARTS_ENTERTAINMENT", "virtual_documents": [ { "country": "US", "document_type": "DRIVING_LICENCE", "document_value": "1111111111", "id": "38f41ac7-ddb6-44e4-b40c-fa0cf8d05b9d", "state": "CA", "expiry_date": "2025-03-09", "id_issuing_authority": "CA" }, { "country": "US", "document_type": "SSN", "document_value": "*****1112", "id": "a301b04f-c904-4c78-9a8b-9a384c51b497", "state": "CA" } ], "zipcode": "95053" } ``` **Business User** ``` { "address_line1": "500 8 El Camino Real Santa Clara", "city": "Santa Clara", "company_website": "www.example.com", "country": "US", "created_at": "2022-04-22T02:21:23.084565", "date_of_birth": "1995-01-01", "email": "example@mail.com", "first_name": "Machnet Technologies Inc", "id": {{UUID}}, "ip_address": "10.0.10.5", "mailing_address": { "address_line1": "500 8 El Camino Real Santa Clara", "city": "Santa Clara", "country": "US", "state": "CA", "zipcode": "95053" }, "mobile_phone": "222222222", "number_of_employee": "BETWEEN_25_TO_50", "number_of_transaction_per_month": 122, "physical_documents": [ { "document_type": "CERTIFICATE_OF_INCORPORATION", "id": {{UUID}} }, { "document_type": "BANK_STATEMENT", "id": {{UUID}} } ], "state": "CA", "status": "UNVERIFIED", "transaction_frequency": "WEEKLY", "user_scope": "COMPUTER_TECHNOLOGY", "zipcode": "95053" } ``` {% endtab %} {% endtabs %} # Business Representatives Read for details on adding, updating and retrieving business representatives For every business user, you will have to provide information on corresponding business representatives to complete your registration. Business representatives include: 1. Account operator 2. Beneficial owners (25% or more ownership of the company) 3. Compliance contact 4. Primary controlling officer {% hint style="info" %} If a business owns more than 25% of the company, the beneficial owners of the business stakeholder should also be provided. {% endhint %} # Business Representatives Object Read for details on adding, updating and retrieving business representatives {% tabs %} {% tab title="Details" %}
FieldRequiredTypeDescription
first_nameYesStringFirst name of the business representative.
middle_nameNoStringMiddle name of the business representative.
last_nameYesStringFamily name of the business representative.
date_of_birthYesStringDate of birth of business representative
address_line1YesStringStreet address of the business representative.
cityYesStringCity of the business representative.
stateYesString2-letter ISO code of the business representative’s state.
countryYesString2-letter ISO code of the business representative’s country.
zipcodeYesStringZip code of the business representative’s address.
typeYesCategory

Enumerated value: ‘ACCOUNT_OPERATOR’, ‘BENEFICIAL_OWNER’, ‘COMPLIANCE’, 'PRIMARY CONTROLLER’

Note: This field will be deprecated. Suggested to use br_type.

br_typeYesObjectSet true or fasle based on what type of business representative you are creating.
br_type.account_operatorYesBoolean

True or False.

To initiate KYB, “ACCOUNT OPERATOR” is required.

br_type.beneficial_ownerYesBooleanSet True or False.
br_type.complianceYesBooleanSet True or False.
br_type.primary controllerYesBooleanSet True or False.
emailYesStringEmail id of the business representative.
virtual_documentsConditionalObjectIdentification document's information. Details on the required documents are outlined in your spec sheet.
virtual_documents.document_typeYes, if virtual_documents is providedStringEnumerated values are listed below.
virtual_documents.document_valueYes, if virtual_documents is providedStringID number of the document.
virtual_documents.issue_dateConditionalStringDate of issue of the document.
virtual_documents.id_issuing_authorityConditionalStringThe department issuing the ID.
virtual_documents.countryConditionalString2-letter ISO code of the user's country.
virtual_documents.stateConditionalString2-letter ISO code of the user's state.
virtual_documents.expiry_dateConditionalStringDate of expiry of the document.
physical_documentsConditionalObjectCopy of a document. Details on the required documents are outlined in your spec sheet.
physical_documents.document_valueYes, if physical_documents is providedStringValue of the document. Physical documents must be encoded Base64 before being uploaded to our system.
physical_documents.document_value_backYes, if physical_documents is providedStringValue of the rear side of the document. Physical documents must be encoded Base64 before being uploaded to our system.
physical_documents.document_typeYes, if physical_documents is providedStringEnumerated values are listed below.
physical_documents.countryConditionalString2-letter ISO code of the user’s country.
physical_documents.stateConditionalString2-letter ISO code of the user’s state.
physical_documents.expiry_dateConditionalStringDate of expiry of the document.
phoneYesNumericMobile number of the contact person.
genderYesStringGender of business representative.
titleYesStringTitle of buinsess representative.
ownership_percentageYes, if Beneficial OwnerNumericMandatory field for business representative of type “beneficial owner”.
**Physical Document Type Enumerated Values** ``` PASSPORT DRIVING_LICENCE STATE_ID ``` **Virtual Document Type Enumerated Values** ``` SSN PASSPORT DRIVING_LICENSE STATE_ID ``` {% endtab %} {% endtabs %} # Add Business Representatives Read for details on adding business representatives **`POST /users/{{user_id}}/business-representative`** {% tabs %} {% tab title="Request Sample" %} ``` curl --location --request POST '{{url}}/users/{{user_id}}/business-representative' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "John", "middle_name": null, "last_name": "Sherpa", "city": "San Jose", "email":"john.sherpa@yahoo.com", "gender": "male", "mobile_phone": "5417543010", "state": "CA", "country": "US", "zipcode": "99705", "address_line1": "123 Main Street Room 22", "date_of_birth": "1997-09-08", "br_type": { "account_operator": true, "beneficial_owner": false, "compliance": false, "primary_controller": false }, "title":"CEO", "virtual_documents": [ { "document_value": "111111111", "document_type": "SSN", "country": "US", "state": "CA", "issue_date": "2018-01-01", "id_issuing_authority": "POTUS" } ], "physical_documents": [ { "document_value": "data:image/jpg;base64,SUQsasasasas909090==", "document_value_back": "data:image/jpg;base64,SUQsasasasas909090==", "document_type": "PASSPORT", "country": "US", "state": "CA", "expiry_date": "2023-11-11" } ] }' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "address_line1": "123 Main Street Room 22", "city": "North Pole", "date_of_birth": "1997-09-08", "email":"john.sherpa@yahoo.com" "first_name": "John", "gender":"male", "id": {{UUID}}, "last_name": "Sherpa", "mobile_phone": "5417543010", "ownership_percentage":0, "physical_documents": [ { "country": "US", "expiry_date": "2023-11-11", "id": "b40d5340-7a39-400c-a85b-38526e6cfb86", "state": "CA", "document_type": "PASSPORT" } ], "state": "CA", "title": "CEO", "virtual_documents": [ { "country": "US", "document_value": "*****1111", "id": {{UUID}}, "state": "CA", "document_type": "SSN", "id_issuing_authority": "POTUS", "issue_date": "2018-01-01" } ], "zipcode": "99705", "br_type": { "account_operator": true, "beneficial_owner": false, "compliance": false, "primary_controller": false }, "country": "US", } ``` {% endtab %} {% endtabs %} # Update Business Representatives Read for details on adding, updating and retrieving business representatives **PATCH `/users/{{user_id}}/business-representative/{{id}}`** {% tabs %} {% tab title="Details" %} **Updatable fields for business representative** | **Fields** | **Send user is verified** | **Send user is not verified** | **Additional details** | | ------------------- | ------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------- | | first\_name | Yes | Yes | | | middle\_name | Yes | Yes | | | last\_name | Yes | Yes | | | date\_of\_birth | Yes | Yes | | | address\_line1 | Yes | Yes | | | city | Yes | Yes | | | state | Yes | Yes | | | country | No | No | | | zipcode | Yes | Yes | | | br\_type | No | No | | | virtual\_documents | Yes | Yes | | | physical\_documents | Yes | Yes | Updating physical\_document object will add a new copy of the document and archive the older one. | | {% endtab %} | | | | {% tab title="Request Sample" %} ``` curl --location --request PATCH '{{url}}/users/{{user_id}}/business-representative/{{id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "John", "middle_name": null, "last_name": "Sherpa", "city": "North Pole", "state": "CA", "country": "US", "zipcode": "99705", "address_line1": "123 Main Street Room 22", "date_of_birth": "1997-09-08", "physical_documents": [ { "document_value": "data:image/jpg;base64,SUQsasasasas909090==", "document_value_back": "data:image/jpg;base64,SUQsasasas()()==", "document_type": "DRIVING_LICENCE" } ], "virtual_documents": [ { "document_value": "222222222", "document_type": "SSN" } ] }' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "address_line1": "123 Main Street Room 22", "city": "North Pole", "date_of_birth": "1997-09-08", "email":"jonh.sherpa@yahoo.com", "first_name": "John", "gender":"male", "id": {{UUID}}, "last_name": "Sherpa", "mobile_phone":"5417543010", "ownership_percentage":0, "physical_documents": [ { "id": {{UUID}}, "document_type": "DRIVING_LICENCE" } ], "state": "CA", "title":"CEO", "virtual_documents": [ { "document_value": "*****2222", "id": {{UUID}}, "document_type": "SSN" } ], "zipcode": "99705", "br_type": { "account_operator": true, "beneficial_owner": false, "compliance": false, "primary_controller": false }, "country": "US", } ``` {% endtab %} {% endtabs %} # Get Business Representatives Read for details on retrieving business representatives **Get a business representative's details** **GET `/users/{{user_id}}/business-representative/{{id}}`** {% tabs %} {% tab title="Request Sample" %} ``` curl --location --request GET '{{url}}/users/{{user_id}}/business-representative/{{id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "address_line1": "123 Main Street Room 22", "city": "North Pole", "date_of_birth": "1997-09-08", "email":"john.sherpa@yahoo.com", "first_name": "John", "gender":"male", "id": {{UUID}}, "last_name": "Sherpa", "mobile_phone":"5417543010", "ownership_percentage":0, "physical_documents": [ { "country": "US", "expiry_date": "2023-11-11", "id":{{UUID}}, "state": "CA", "document_type": "PASSPORT", } ], "state": "CA", "title":"CEO", "virtual_documents": [ { "country": "US", "document_value": "*****1111", "id": {{UUID}}, "state": "CA", "document_type": "SSN", "id_issuing_authority": "POTUS", "issue_date": "2018-01-01" } ], "zipcode": "99705", "br_type": { "account_operator": true, "beneficial_owner": false, "compliance": false, "primary_controller": false }, "country": "US", } ``` {% endtab %} {% endtabs %} **Get list of all business representative** **GET `/users/{{user_id}}/business-representative`** {% tabs %} {% tab title="Request Sample" %} ``` curl --location --request GET '{{url}}/users/{{user_id}}/business-representative' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '' ``` {% endtab %} {% tab title="Response Sample" %} ``` [ { "address_line1": "500 8 El Camino Real Santa Clara", "city": "CA", "date_of_birth": "1997-09-08", "email": "john.sherpa@yahoo.com", "first_name": "John", "gender": "male", "id": {{UUID}}, "last_name": "Sherpa", "mobile_phone": "5417543010", "ownership_percentage": 0, "physical_documents": [ { "country": "US", "expiry_date": "2023-11-11", "id":{{UUID}}, "state": "CA", "document_type": "PASSPORT", } ], "state": "CA", "title": "CEO", "virtual_documents": [ { "country": "US", "document_value": "*****1111", "id": {{UUID}}, "state": "CA", "document_type": "SSN", "id_issuing_authority": "POTUS", "issue_date": "2018-01-01" } ], "zipcode": "99705", "br_type": { "account_operator": true, "beneficial_owner": false, "compliance": false, "primary_controller": false }, "country": "US" }, { "address_line1": "500 8 El Camino Real Santa Clara", "city": "CA", "date_of_birth": "1997-09-08", "email": "jane.sherpa@yahoo.com", "first_name": "Jane", "gender": "female", "id": {{UUID}}, "last_name": "Sherpa", "mobile_phone": "5417543010", "ownership_percentage": 0, "physical_documents": [ { "country": "US", "expiry_date": "2023-11-11", "id": "69313afa-3e27-4adc-a0f0-e750b95152f3", "state": "CA", "document_type": "PASSPORT" } ], "state": "CA", "title": "CEO", "virtual_documents": [ { "country": "US", "document_value": "*****2222", "id": "6f0ff320-5062-41fd-86f7-4242b52f52e8", "state": "CA", "document_type": "SSN", "id_issuing_authority": "POTUS", "issue_date": "2018-10-01" } ], "zipcode": "95053", "br_type": { "account_operator": true, "beneficial_owner": false, "compliance": false, "primary_controller": false }, "country": "US" } ] ``` {% endtab %} {% endtabs %} # Declaration Read on for details on declaration for business wallet Business users who want to create a business wallet need to declare their UBO or Ultimate Beneficial Owner, any member who holds 25% or more ownership of the business. The business users will also need to declare additional details on the business. # Declaration Object Read about Declaration object details {% tabs %} {% tab title="Details" %}
FieldRequiredTypeDescription
cryptopcurrencyYesBooleanSet as false if business is not involved with cryptocurrency
public_companyYesBooleanSet as false if business is not a public company
majority_owned_by_listedYesBooleanSet as false if business is not majority owned (50% or more) by a public company
registered_SECYesBooleanSet as false if business is not registered with U.S. Securities and Exchange Commission (SEC)
regulated_financialYesBooleanSet as false if business is not a regulated financial company
gamblingYesBooleanSet as false if business is not involved with the internet gambling business
federalYesBooleanSet as false if the business does not have Money Transmission Licenses (MTL) in any state
statesYesStringIf federal is set to true, the states that you have licenses in needs to be provided Eg: ["CA", "AL"]
compliance_idYesStringID of the business representative of type ‘COMPLIANCE’. Compliance contact must be previously added using the Business Representative API
primary_controller_idYesStringID of the business representative of type PRIMARY CONTROLLER. Primary controller must be previously added using the Business Representative API
attestedYesBooleanMust be set as true. This signifies that the user has confirmed to the UBO declaration statement
{% endtab %} {% endtabs %} Note: Business user representative needs to attest to the following statements. *I certify that the following information was submitted to Platform for all beneficial owners (holding 25% or more ownership) and controlling persons & executives:* * *US Person(s): SSN + US Government Issued Photo ID* * *Foreign Person(s): Tax Identification Number (if available) + Passport Number & Country of Issuance. In lieu of passport number, foreign persons may also provide an alien identification card number, or number and country of issuance of any other government issued photo ID evidencing nationality or residence.* # Declaration Read on details on declaring UBO **`PATCH /users/{user_id}/ubo_declare`** {% tabs %} {% tab title="Request" %} ``` curl --location --request PATCH 'https://v4test.machpay.com/v4/users/95838646-46f2-48b5-bdaf-ad2cd49cee96/ubo_declare' \ --header 'X-Client-Id: 457dde89-76d4-41ac-97ee-f4a4321591d8' \ --header 'X-Client-Secret: c562435e-cb80-4df1-aa11-205a2df56b6a' \ --header 'Content-Type: application/json' \ --data-raw '{ "cryptocurrency": false, "public_company": false, "majority_owned_by_listed": false, "registered_SEC": false, "regulated_financial": false, "gambling": false, "primary_controller_id": "d1e1105a-1300-4572-9247-6fbd88e14e35", "compliance_id": "d1e1105a-1300-4572-9247-6fbd88e14e35", "federal": false, "attested": true, "states": [] }' ``` {% endtab %} {% tab title="Response" %} ``` HTTP status code: 204 No Content ``` {% endtab %} {% endtabs %} # Initiate Verification Read on verification of users This enables you to initiate the user's KYC/KYB process. Basic information for the individual or business user must be provided before initiating user's KYC/KYB. If additional information is added or any information is updated on the user, KYC/KYB should be re-initiated using this API. #### `POST /users/{{user_id}}/kyc` {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request POST '{{url}}/users/{{user_id}}/kyc' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "success": true, "status": "INITIATED" } ``` {% endtab %} {% endtabs %} The status of the user changes from "UNVERIFIED" at the beginning to "IN PROGRESS" to "VERIFIED" eventually if the KYC/KYB process is complete and successful. Details on the statuses can be found [here](/api-references/user/registration/user-verification-status). # Get User by ID Read on obtaining information about a registered user You can retrieve detailed information about a particular user using their user ID. #### `GET /users/{{user_id}}` {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request GET '{{url}}/users/{{user_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "address_line1": "500 8 El Camino Real Santa Clara", "city": "Santa Clara", "company_details": { "address": "123 address st", "company_name": "ACME", "phone_number": "2222222222" }, "country": "US", "created_at": "2022-03-29T15:59:03.699517", "date_of_birth": "2000-01-01", "email": "norgay@test.com", "first_name": "Tenzin", "gender": "female", "id": "f45680e1-014d-42c7-be86-3b2899e911c3", "ip_address": "10.0.0.1", "last_name": "Norgay", "middle_name": "", "mobile_phone": "2106603032", "occupation": "Banker", "physical_documents": [ { "document_type": "BANK_STATEMENT", "id": "9f57c7c9-ffa5-4e88-a28a-af3af1232a46" }, { "country": "US", "document_type": "DRIVING_LICENCE", "id": "d20dd857-7dc0-4abc-879f-fcfb15f4423d", "state": "CA" } ], "state": "CA", "status": "UNVERIFIED", "user_scope": "ARTS_ENTERTAINMENT", "virtual_documents": [ { "country": "US", "document_type": "SSN", "document_value": "*****1112", "id": "a301b04f-c904-4c78-9a8b-9a384c51b497", "state": "CA" }, { "country": "US", "document_type": "DRIVING_LICENCE", "document_value": "1111111111", "id": "38f41ac7-ddb6-44e4-b40c-fa0cf8d05b9d", "state": "CA", "expiry_date": "2025-03-09", "id_issuing_authority": "CA" } ], "zipcode": "95053", "business": false, "type": "SEND" } ``` {% endtab %} {% endtabs %} # Get Verification Status Read on verification status of submitted user information You can get the verification status of each KYC/KYB information (CIP tag) a user has submitted through this API. Only the status of submitted information will be presented here, however, you may be required to collect more information based on your spec sheet for a user's transaction to be processed. The verification status can be any of the following. Details are also outlined [here](/api-references/user/registration/cip-information-status). | | | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Verification Status** | **Description** | | SUBMIT | CIP tag has been successfully submitted | | REVIEWING | CIP tag is under review | | VERIFIED | CIP tag is verified | | FAILED | CIP tag verification failed | | REQUESTED | CIP tag is required for the user. This usually occurs when a user has created a transaction above their current tier limits and additional KYC information is required to further process the transaction. | #### `GET /users/{{user_id}}/cip-info` {% tabs %} {% tab title="Request Sample" %} ``` curl --location --request GET '{{url}}/users/{{user_id}}/cip-info' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} **Individual user** ``` { "cip_info": { "GENDER": "VERIFIED", "COUNTRY": "VERIFIED", "STATE": "VERIFIED", "LAST_NAME": "VERIFIED", "OCCUPATION": "SUBMIT", "CITY": "VERIFIED", "ZIP_CODE": "VERIFIED", "DATE_OF_BIRTH": "VERIFIED", "ID_DOC": "VERIFIED", "PHONE_NUMBER": "VERIFIED", "EMAIL": "VERIFIED", "ADDRESS_LINE1": "VERIFIED", "MIDDLE_NAME": "SUBMIT", "FIRST_NAME": "VERIFIED", "IP_ADDRESS": "VERIFIED" }, "kyc_status": "VERIFIED", "user_id": UUID } ``` **Business user** ``` { "cip_info": { "NATURE_OF_BUSINESS": "VERIFIED", "COMPANY_TYPE": "VERIFIED", "EIN_NUMBER": "VERIFIED", "ACCOUNT_OPERATOR_INFO": "VERIFIED", "ZIP_CODE": "VERIFIED", "EMAIL": "VERIFIED", "CERTIFICATE_OF_INCORPORATION": "VERIFIED", "TXN_FREQUENCY": "VERIFIED", "NO_OF_EMPLOYEE": "VERIFIED", "DATE_OF_BIRTH": "VERIFIED", "EIN_DOC": "VERIFIED", "FIRST_NAME": "VERIFIED", "NO_OF_TXN_PER_MONTH": "VERIFIED", "MAILING_ADDRESS": "VERIFIED", "STATE": "VERIFIED", "SOURCE_OF_FUND": "VERIFIED", "ADDRESS_LINE1": "VERIFIED", "COUNTRY": "VERIFIED", "PHONE_NUMBER": "VERIFIED", "COMPANY_WEBSITE": "VERIFIED", "CITY": "VERIFIED" }, "kyc_status": "VERIFIED", "user_id": {{UUID}} } ``` {% endtab %} {% endtabs %} # Add a Receive User Read on how to add a receive user You will have to create an individual or business receive user who will receive the funds. In order to enable receive capabilities to a user, you need to create a user with "type": "RECEIVE". Receive users will be linked to a particular send user and only users in destination corridors enabled for you can have receive capabilities. #### `POST /users` {% tabs %} {% tab title="Request Sample" %} **Individual Receive User** ``` curl --location --request POST '{{url}}/users \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "Edmund", "middle_name": "", "last_name": "Hillary", "email":"ednund.hillary@test.com", "gender": "male", "date_of_birth":"2000-01-01", "mobile_phone": "9879879870", "address_line1": "500 El Camino Real Santa Clara", "city": "Santa Clara", "zipcode": "95053", "state": "CA", "country":"US", "business":false, "occupation":"Engineer", "ip_address":"10.0.0.1", "user_relationship": "BROTHER", "send_user_id":UUID, "type":"RECEIVE" }' ``` **Business Receive User** ``` curl --location --request POST '{{url}}/users \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "Everest pvt Ltd", "middle_name": null, "last_name": null, "mobile_phone": "5433456478", "address_line1": "Cra.23 No.20B-01, El Retiro", "city": "Antioquia", "zipcode": "95053", "country": "CO", "send_user_id": {{UUID}}, "type": "RECEIVE", "business": true, "virtual_documents": [ { "document_value": "12345", "document_type": "EIN_NUMBER" } ] }' ``` {% endtab %} {% tab title="Response Sample" %} **Individual Receive User** ``` { "address_line1": "500 El Camino Real Santa Clara", "business": false, "city": "Santa Clara", "country": "US", "date_of_birth": "2000-01-01", "email": "edmund.hillary@test.com", "first_name": "edmund", "gender": "male", "id": "23a1f436-f75c-4c9c-9563-7812f9bcc135", "ip_address": "10.0.0.1", "last_name": "hillary", "middle_name": "", "mobile_phone": "9879879870", "occupation": "Engineer", "state": "CA", "status": "UNVERIFIED", "tier": 0, "type": "RECEIVE", "user_relationship": "BROTHER", "zipcode": "95053" } ``` **Business Receive User** ``` { "address_line1": "Cra.23 No.20B-01, El Retiro", "city": "Antioquia", "country": "CO", "created_at": "2022-05-12T08:40:22.309626", "first_name": "Everest pvt Ltd", "id": {{UUID}}, "mobile_phone": "5433456478", "physical_documents": [], "send_user_id": {{UUID}}, "status": "UNVERIFIED", "virtual_documents": [ { "document_type": "EIN_NUMBER", "document_value": "12345", "id": {{UUID}} } ], "zipcode": "95053", "business": true, "type": "RECEIVE" } ``` {% endtab %} {% endtabs %} # Update a Receive User This API allows you to update the receive user information. Receive user details can only be updated if no transactions have been forwarded for delivery for the user. Hence, a receive user can only be updated when Delivery Status is NONE and in some cases, DELIVERY HOLD. #### `PATCH /users/{{receive_user_id}}` {% tabs %} {% tab title="Individual" %} | **Fields** | **Updatable** | **Additional Details** | | --------------------------- | ------------- | ------------------------------------------------------------------------------------------------- | | first\_name | Yes | | | middle\_name | Yes | | | last\_number | Yes | | | gender | No | Can only be updated if not provided earlier | | mobile\_phone | Yes | | | date\_of*\_*birth | Yes | | | email | Yes | | | occupation | No | Can only be updated if not provided earlier | | user\_relationship | No | Can only be updated if not provided earlier | | address\_line1 | Yes | | | address\_line2 | Yes | | | city | Yes | | | state | Yes | | | country | No | | | zipcode | Yes | | | physical\_documents | Yes | Updating physical\_document object will add a new copy of the document and archive the older one. | | virtual\_documents | Yes | | | {% endtab %} | | | {% tab title="Business" %} | **Fields** | **Updatable** | **Remarks** | | ------------------- | ------------- | ----------- | | first\_name | Yes | | | mobile\_number | Yes | | | virtual\_documents | No | | | physical\_documents | Yes | | | address\_line1 | Yes | | | address\_line2 | Yes | | | state | Yes | | | city | Yes | | | zipcode | Yes | | | country | No | | | {% endtab %} | | | {% tab title="Request Sample" %} ``` curl --location -g --request PATCH '{{url}}/users/{{receive_user_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_name": "raman", "last_name": "machnett", "email": "pd.p@gmail.com", "date_of_birth": "2000-01-02", "mobile_phone": "237653801975", "send_user_id":"3cf826ea-1d0c-46a8-a93e-4c8dc9cfbf80", "physical_documents": [ { "document_value": "data:image/jpg;base64,SUQsasasasas909090==", "document_value_back": "data:image/jpg;base64,SUQsasasasas909090==", "document_type": "OTHER", "custom_document_type": "citizenship", "country": "US", "state": "Ak" } ], "virtual_documents": [ { "document_value": "111111112", "document_type": "OTHER", "custom_document_type": "citizenship", "expiry_date": "2025-03-10", "id_issuing_authority": "MN", "country": "US", "state": "Ak" } ] }' ``` {% endtab %} {% tab title="Response" %} ``` { "address_line2": "500 8 El Camino Real Santa Clara", "city": "Santa Clara", "country": "GH", "created_at": "2022-09-30T04:46:59.167529", "date_of_birth": "2000-01-02", "email": "pd.p@gmail.com", "first_name": "raman", "gender": "female", "id": "3cf826ea-1d0c-46a8-a93e-4c8dc9cfbf80", "ip_address": "10.0.0.1", "last_name": "machnett", "mobile_phone": "237653801975", "occupation": "QA", "physical_documents": [ { "country": "US", "custom_document_type": "citizenship", "document_type": "OTHER", "id": "1731c62b-a95e-4a59-94e1-cfbe5c95978a", "state": "Ak" } ], "status": "UNVERIFIED", "user_relationship": "SISTER", "virtual_documents": [ { "country": "US", "custom_document_type": "citizenship", "document_type": "OTHER", "document_value": "111111112", "id": "f937c333-e76d-4fd2-b02c-01a013857ea3", "state": "Ak", "expiry_date": "2025-03-10", "id_issuing_authority": "MN" } ], "zipcode": "23775-9K" } ``` {% endtab %} {% endtabs %} # Get Receive User List Read for details on added receive users You can retrieve information about all the receive users linked to a particular user. #### `GET /users/{{user_id}}/receive-users` {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request GET '{{url}}/users/{{user_id}}/receive-users' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` [ { "address_line1": "500 El Camino Real Santa Clara", "city": "Santa Clara", "country": "US", "date_of_birth": "2000-01-01", "email": "edmundH@test.com", "first_name": "Edmund", "gender": "male", "id": {{UUID}}, "last_name": "Hillary", "middle_name": "", "mobile_phone": "9879879870", "occupation": "Engineer", "send_user_id": {{UUID}}, "state": "CA", "user_relationship": "BROTHER", "zipcode": "95053" "business": false, "type": "RECEIVE" }, { "address_line1": "Cra.23 No.20B-01, El Retiro", "city": "Antioquia", "country": "CO", "created_at": "2022-05-12T10:25:58.777292", "first_name": "Everest pvt Ltd", "id": {{UUID}}, "mobile_phone": "5433456478", "physical_documents": [], "send_user_id": {{UUID}}, "status": "UNVERIFIED", "user_relationship": "BROTHER", "virtual_documents": [ { "document_type": "EIN_NUMBER", "document_value": "12345", "id": {{UUID}} } ], "zipcode": "95053", "business": true, "type": "RECEIVE" } ] ``` {% endtab %} {% endtabs %} # Funds Read on adding funding accounts for users. ## Overview In order to be able to send money, the user will have to link a funding source. Currently, we support payment using bank accounts and debit cards. All bank accounts and debit cards need to be added using Machnet's widget in order to remain compliant. However, specific details of the funding account can be obtained through an API. The response can be stored on your end for further operations such as Create Transaction, etc. Receive users may also have an account associated with them to receive the funds. There are specific endpoints to add receive accounts for a receive user. # User Funding Account Object Details on funding account object {% tabs %} {% tab title="Details" %} | **Field** | **Type** | **Description** | | --------------------- | -------- | ----------------------------------------------------------------- | | account\_type | String | Type of bank account. Enumerated value CHECKING or SAVINGS | | account\_number | String | Last 4 digits of the funding account number | | institution\_name | String | Name of the institution/bank associated with the account | | verification\_status | String | Enumerated value: PENDING, VERIFIED, FAILED, and LOGIN\_REQUIRED. | | funding\_source\_type | String | Enumerated value: CARD, BANK\_ACCOUNT | | id | UUID | ID of the account | | user\_id | UUID | User’s ID | | funding\_source\_name | String | Name of the funding account | | type | String | Enumerated value BANK\_ACCOUNT, CARD | | {% endtab %} | | | | {% endtabs %} | | | # Funding Account Widget Read on adding funding accounts in safe and secure way You will need to use our widget with the type "CARD" to add a card or "BANK" to add a bank as a funding account. A particular user can only have 2 active bank and 2 active card accounts. To initialize the widget, you will need to first generate a Widget Token, which will only be valid for a certain time period. You will need to pass this token along with the Sender ID to widget initialization snippets. #### `GET /users/{{user_id}}/widget-token` {% tabs %} {% tab title="Response Parameters" %} | **Field** | **Required** | **Type** | **Description** | | --------------- | ------------ | -------- | ------------------- | | token | Yes | String | Token Details | | user\_id | Yes | UUID | User ID | | expiry\_minutes | Yes | Numeric | Token validity time | | {% endtab %} | | | | {% tab title="Request Sample" %} ``` curl --location -g --request GET '{{url}}/users/{{user_id}}/widget-token' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "expiry_minutes": 15, "user_id": "85e1595e-4b08-44d6-acdf-e842149e8f6a", "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZW5kZXJJZCI6Ik9EVmxNVFU1TldVdE5HSXdPQzAwTkdRMkxXRmpaR1l0WlRnME1qRTBPV1U0WmpaaFxyXG4iLCJtdG9JZCI6IlFUQXdNd1xyXG4iLCJyb2xlcyI6WyJXSURHRVQiXSwib3JpZ2luYXRvciI6IkEwMDMiLCJleHAiOjE2MzYzMzkxMDEsImFmZmlsaWF0ZSI6IkEwMDMiLCJhZmZpbGlhdGVJZCI6NH0.JEXzaJeqpREbi2j1krWfgTAAKmS9Lh3q7PFpYppO4dU" } ``` {% endtab %} {% endtabs %} After you have the Widget Token, you will need to follow the steps mentioned below to set up the widget. ### **1. Include the Widget Script** ``` ``` ### **2. Create a div where widget needs to be placed** ```
``` ### **3. Initialize the Widget** {% tabs %} {% tab title="For Card" %} ``` ``` {% endtab %} {% tab title="For Bank" %} ``` ``` {% endtab %} {% endtabs %} [Funding account webhooks](/api-references/webhooks/events#funding-account-events) and[ widget events](/api-references/webhooks/events#widget-events) will provide details on the status of the process. # OAuth Integration Read about supporting OAuth integrations There are two types of flows that users can be directed towards while adding a bank account. 1. Non-OAuth: Users authenticate and permission data directly from the widget to allow us access to their financial accounts. 2. OAuth: OAuth provides a more secure connection for your users as credentials are handled entirely by the OAuth provider (bank) and exchanged for a token that we can use. OAuth connections are predefined based on the bank's policies and our integrations. To connect accounts via OAuth, users will be directed to the bank's website for authentication and authorization. Once the user grants permission, the user will have to be redirected to our widget to complete the flow. The permission account will be connected and users will have to select a specific bank account (savings or checking) from the connected bank to be add to our platform. ### OAuth for Web For non-OAuth flow, all events will need to be completed in Machnet's widget. For OAuth flow, when a user selects an OAuth supported bank and confirms in the widget, a new tab will open in their current browser. Once the user grants the required permissions, the tab will close by itself and the user will be redirected to the previous tab where they can see that the connection is being established. Once the connection is established, user will have to select the bank account they would like to use from the list of savings and checking accounts available in the connected bank. Note: We recommend you to not use ‘appScheme’ for browsers. ### Webview widget for mobile application For non-OAuth flow, all events will need to be completed in the widget in webview. For OAuth flow, when a user selects an OAuth supported bank and confirms in the widget, the user will be redirected to their bank’s website. Once the user grants the required permissions to link the bank with our system, the browser will redirect the user to the appScheme. You will need to make sure you set the ‘appScheme’ to the deep link of your application when you load the bank widget. If this field is not set while loading the widget, the user will not be automatically redirected to your app upon completion of the OAuth flow.
# Bank Verification Status Read on dealing with bank verification statuses After a bank account has been connected using our widget, the bank account undergoes verification before it is successfully added. The bank account will have different verification statuses which you can retrieve using our API or through webhooks. 1. **PENDING**: Once the bank account has been added through the widget, verification checks are conducted on the bank account. While the verification checks are in progress, verification\_status of the funding account will be PENDING. 1. You can retrieve verification status using the GET User funding account API. 2. `user_bank_verification_pending` webhook will also be sent to the subscribed link. 2. **VERIFIED**: When all verification checks are completed and the bank account is successfully added, the verification\_status of the user’s funding account will be moved to VERIFIED. 1. You can retrieve verification status using the GET User funding account API. 2. `user_bank_added` webhook will also be sent to the subscribed link. 3. **FAILED**: If verification checks are unsuccessful or there is an issue, the verification\_status of the user’s funding account will be moved to FAILED. 1. You can retrieve verification status using the GET User funding account API. 2. `user_bank_verification_failed` webhook will also be sent to the subscribed link. 4. **LOGIN\_REQUIRED**: In some cases, the user may be required to re-login to their bank account.The verification\_status of the user’s funding account will be moved to LOGIN\_REQUIRED. 1. You can retrieve verification status using the GET User funding account API. 2. `bank_login_required` webhook will be sent to the subscribed link. 3. You will have to reopen the bank widget with the funding account ID so they can re-login to their bank account. 4. Please note that for certain cases the user may need to communicate with their bank before re-linking their bank account. When verification status of the user’s funding account is PENDING, users can create a transaction/transfer. However, the transaction will be placed on HOLD. Only when the user’s funding account is in VERIFIED status, the transaction will be forwarded for processing, given that all other compliance checks have been completed.
# Wallet Object Details on Wallet object {% tabs %} {% tab title="Details" %} | **Field** | **Required** | **Type** | **Description** | | -------------------------- | ------------ | -------- | ---------------------------------------------------------------------------------- | | nick\_name | Yes | String | Nickname for the wallet | | funding\_source\_type | In Response | String | Response Type of funding source. “WALLET” | | id | In Response | String | Unique wallet ID once a wallet is successfully created | | user\_id | Yes | UUID | ID of the wallet user | | balance.available\_balance | In Response | String | Balance available for transfer | | balance.balance | In Response | String | Total balance in the wallet including the transactions in transition | | verification\_status | In Response | String | Verification status of wallet. Wallet in verified status can be used for transfers | | annual\_limit | In Response | Numeric | User's maximum annual transaction limit | | daily\_limit | In Response | Numeric | User's maximum daily transaction limit | | monthly\_limit | In Response | Numeric | User's maximum monthly transaction limit | | current\_tier | In Response | Numeric | User tier level. Additional details on the tiers can be found on your spec sheet | | max\_wallet\_tier\_limit | In Response | Numeric | Maximum amount the wallet can hold | {% endtab %} {% endtabs %} # Create a Wallet Read on adding wallet as funding source You can use this API to create wallet funding account for users. A user must be registered and KYC/KYB must be VERIFIED before a wallet funding source can be added for the user. To register a user and conduct their KYC/KYB, please follow the details [here](/api-references/user/initiate-verification). Please also note that for business users, they be registered with `deposit_enabled`: true for them to be able to create a wallet. Only one wallet account can be added for a specific verified user. #### **`POST /users/{userId}/funds/wallets`** {% tabs %} {% tab title="Parameters" %} | **Field** | **Type** | **Description** | | --------------------- | -------- | --------------------------------------------------------------------- | | funding\_source\_type | String | Response Type of funding source “WALLET” | | id | String | Unique wallet ID once a wallet is successfully created | | user\_id | UUID | ID of the wallet user | | verification\_status | String | Status of wallet. Wallet in verified status can be used for transfers | | nick\_name | String | Nickname for the wallet | {% endtab %} {% tab title="Request Sample" %} ``` curl --location -g --request POST '{{url}}/users/{{userId}}/funds/wallets' \ --header 'X-Client-Id:{{client_id}} ' \ --header 'X-Client-Secret:{{client_secret}}' \ --data-raw '{ "nick_name": "My Wallet" }' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "funding_source_type": "WALLET", "id": UUID, "user_id": UUID, "verification_status": "VERIFIED", "nick_name": "My Wallet" } ``` {% endtab %} {% endtabs %} # Get Wallet Details Read on obtaining information on added individual wallet accounts You can retrieve details about a user's wallet using this API. #### **`GET /users/{{userId}}/funds/{{wallet_id}}`** {% tabs %} {% tab title="Parameters" %} | **Field** | **Type** | **Description** | | -------------------------- | -------- | -------------------------------------------------------------------------- | | balance.available\_balance | Numeric | Balance available for transfer | | balance.balance | Numeric | Total balance in the wallet including the transactions in transition | | funding\_source\_type | String | Type of funding source. "WALLET" | | id | String | Unique wallet ID once a wallet is successfully created | | nick\_name | String | Nickname for the wallet | | user\_id | UUID | ID of the wallet user | | verification\_status | String | Status of wallet. Wallet in verified status can only be used for transfers | {% endtab %} {% tab title="Request Sample" %} ``` curl --location -g --request POST ‘{{url}}/users/{{userId}}/funds/{{wallet_id}}' \ --header 'X-Client-Id:{{client_id}} ' \ --header 'X-Client-Secret:{{client_secret}}' \ ``` {% endtab %} {% tab title="Response Sample" %} ``` { "balance": { "available_balance": 40.00, "balance": 40.00 }, "funding_source_type": "WALLET", "id": UUID, "nick_name": "My Wallet", "user_id": UUID, "verification_status": "VERIFIED" } ``` {% endtab %} {% endtabs %} # Get User Funding Account Read on obtaining information on funding accounts added by a user **Get list of all funding accounts** You can view all the fundings accounts associated with a user. #### `GET /users/{{user_id}}/funds?type={{funding_source_type}}` {% tabs %} {% tab title="Object Details" %} | **Field** | **Type** | **Description** | | --------------------- | -------- | ---------------------------------------------------------- | | account\_type | String | Type of bank account. Enumerated value CHECKING or SAVINGS | | account\_number | String | Last 4 digits of the funding account number | | institution\_name | String | Name of the institution/bank associated with the account | | verification\_status | String | Enumerated value: PENDING, VERIFIED, FAILED. | | funding\_source\_type | String | Enumerated value: CARD, BANK\_ACCOUNT | | id | UUID | ID of the account | | user\_id | UUID | User’s ID | | funding\_source\_name | String | Name of the funding account | | type | String | Enumerated value BANK\_ACCOUNT, CARD | | {% endtab %} | | | {% tab title="Request Sample" %} **Bank** ``` curl --location -g --request GET '{{url}}/users/{{user_id}}/funds?type=BANK' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` **Card** ``` curl --location -g --request GET '{{url}}/users/{{user_id}}/funds?type=CARD' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} **Bank** ``` [{ "id": UUID, "user_id": UUID, "account_number": "8901", "funding_source_name": "TEST", "funding_source_type": "BANK", "institution_name": "CITIBANK NA", "verification_status": "VERIFIED" }] ``` **Card** 
[{
        "id": UUID,
        "user_id": UUID,
        "account_number": "9991",
        "funding_source_name": "VISA-9991",
        "funding_source_type": "CARD", 
        "institution_name": "VISA",
        "verification_status": "VERIFIED"
 }]
{% endtab %} {% endtabs %} **Get funding account by ID** You can get details of a particular funding account of a send user. #### `GET /users/{{user_id}}/funds/{{fund_id}}` {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request GET '{{url}}/users/{{user_id}}/funds/{{fund_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "id": UUID, "user_id": UUID, "account_number": "9991", "funding_source_name": "VISA-9991", "funding_source_type": "CARD", "institution_name": "VISA", "verification_status": "VERIFIED" } ``` {% endtab %} {% endtabs %} # Delete User Funding Account Read for details on removing a funding account linked to a user You can remove a funding account associated with a user by using this API. Once you remove the account, it will also not be provided when you retrieve the list of funding accounts for the user. A particular user can only have 2 active bank and 2 active card accounts. Please note that users are also able to remove bank accounts directly from the widget. Either way, a webhook will be sent when a funding account is removed. #### `DELETE /users/{{user_id}}/funds/{{fund_id}}` {% tabs %} {% tab title="Request" %} ``` curl --location -g --request DELETE '{{url}}/users/{{user_id}}/funds/{{fund_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response" %} ``` HTTP status : 204 No Content ``` {% endtab %} {% endtabs %} # Add a Receive Account Read on adding a receive account for a receive user You can add receive accounts for users with receive type bank or wallet. You will have to also provide the recipient account information. Please note that you can only deposit business payment transactions to bank accounts. #### `POST /users/{{user_id}}/receive-users/{{receiveUserId}}/accounts` {% tabs %} {% tab title="Request Parameters" %} **Wallet** | | | | | | -------------- | ------------ | -------- | -------------------------------------------------------------------------------------------- | | **Field** | **Required** | **Type** | **Description** | | msisdn | Yes | String | Receive user wallet account number | | wallet\_type | No | String | Enumerated value, Type of receive user wallet: 1. Available value: TEL 2. Default value: TEL | | payer\_id | Yes | Long | Id of payer associated with the wallet | | payout\_method | Yes | String | Enumerated value - WALLET | **Bank** | **Field** | **Required** | **Type** | **Description** | | ---------------- | ------------ | ------------- | -------------------------------------------------- | | account\_number | Yes | Alpha-numeric | Bank account number. | | account\_type | Yes | String | Account type. Enumerated value - CHECKING, SAVINGS | | bank\_id | Yes | numeric | Bank ID | | branch\_id | Yes | numeric | Branch ID | | branch\_location | No | String | Branch location | | swift\_bic\_code | No | String | SWIFT code of bank | | payout\_method | Yes | String | Enumerated value - BANK\_DEPOSIT | | {% endtab %} | | | | {% tab title="Request Sample" %} **Wallet** ``` curl --location -g --request POST '{{url}}/users/{{user_id}}/receive-users/{{receive_user_id}}/accounts' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "msisdn" : "233543225243", "wallet_type" : "TEL", "payer_id" : "100", "payout_method" : "WALLET" }' ``` **Bank** ``` curl --location -g --request POST '{{url}}/users/{{user_id}}/receive-users/{{receiveUserId}}/accounts' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "account_number":"99999999", "account_type":"SAVINGS", "bank_id":4, "branch_location":null, "branch_id":4, "payout_method":"BANK_DEPOSIT" }' ``` {% endtab %} {% tab title="Response Sample" %} **Wallet** ``` { "created_at": "2021-12-07T09:16:33.947037", "id": UUID, "msisdn": "233543225243", "payout_method": "WALLET", "status": "VERIFIED", "user_id": UUID, "wallet_type": "TEL" } ``` **Bank** ``` { "account_number": "99999999", "account_type": "SAVINGS", "bank_id": 4, "branch_id": 4, "created_at": "2021-12-01T03:14:54.481686", "id": UUID, "payout_method": "BANK_DEPOSIT", "status": "UNVERIFIED", "user_id": UUID } ``` {% endtab %} {% endtabs %} # Update a Receive Account Receive accounts of a transaction can only be updated if no transactions have been forwarded for delivery in that particular receive account. Hence, there should be no transactions to a receive account or active transactions should have Delivery Status as NONE and in some cases, DELIVERY HOLD. #### `PATCH /users/{{user_id}}/receive-users/{{receive_user_id}}/accounts/{{receive_user_account_id}}` {% tabs %} {% tab title="Details" %} **Bank** | **Fields** | **Updatable** | | ---------------- | ------------- | | account\_number | Yes | | account\_type | Yes | | bank\_id | Yes | | branch\_location | Yes | | branch\_id | Yes | | swift\_bic\_code | Yes | | rtn\_number | Yes | **Wallet** | **Fields** | **Updatable** | | ------------ | ------------- | | msisdn | Yes | | wallet\_type | No | | payer\_id | Yes | | {% endtab %} | | {% tab title="Request Sample" %} **Bank** ``` curl --location -g --request PATCH '{{url}}/users/{{user_id}}/receive-users/{{receive_user_id}}/accounts/{{receive_user_account_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "account_number": "0037275350", "payout_method": "BANK_DEPOSIT", "account_type": "CHECKING", "bank_id": 4, "branch_id": 45, "branch_location": 1, "rtn_number": "4342492422", "swift_bic_code": "OCCICOBCBO8" }' ``` **Wallet** ``` curl --location -g --request PATCH '{{url}}/users/{{user_id}}/receive-users/{{receive_user_id}}/accounts/{{receive_user_account_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "msisdn": "237653801972", "wallet_type": "TELS", "payer_id": 42, "payout_method": "WALLET" }' ``` {% endtab %} {% tab title="Response Sample" %} **Bank** ``` { "account_number": "0037275350", "account_type": "CHECKING", "bank_id": 4, "branch_id": 45, "branch_location": "1", "created_at": "2022-09-30T04:48:28.26789", "id": "f29e44f7-633d-46cc-bbe2-6197e193eae1", "payout_method": "BANK_DEPOSIT", "status": "UNVERIFIED", "swift_bic_code": "OCCICOBCBO8", "user_id": "51a13748-2684-4ee3-a630-46f2fabf694f" } ``` **Wallet** ``` { "created_at": "2022-09-30T04:56:52.396836", "id": "20e09eb7-d9e4-4aaa-b17b-e1d899b208c0", "msisdn": "237653801972", "payout_method": "WALLET", "status": "VERIFIED", "user_id": "cfafc7b6-7756-45e7-8bb1-9f2f0df4554a", "wallet_type": "TEL" } ``` {% endtab %} {% endtabs %} # Get Receive Accounts Read on obtaining information on added receive accounts ### **Get list of receive accounts** You can fetch all the receive accounts created under a receive user. #### `GET /users/{{user_id}}/receive-users/{{receive_user_id}}/accounts` {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request GET '{{url}}/users/{{user_id}}/receive-users/{{receive_user_id}}/accounts' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} 
{
        "account_number": "0037275353",
        "account_type": "SAVINGS",
        "bank_id": 2,
        "branch_id": 3,
        "created_at": "2021-10-08T11:12:21.957",
        "id": "358d1471-f915-407d-95af-6e72c5dde082",
        "payout_method": "BANK_DEPOSIT",
        "status": "VERIFIED",
        "user_id": "87fa8868-f187-4f0f-aa8d-3815336334c6"
    },
        "created_at": "2021-12-07T09:16:33.947037",
        "id": "94e7db9e-f49d-4573-a9e0-639714248b6f",
        "msisdn": "233242516556",
        "payout_method": "WALLET",
        "status": "VERIFIED",
        "user_id": "f319cd8a-f4f3-465b-bbd8-8457d51f8c57",
        "wallet_type": "TEL"
}
{% endtab %} {% endtabs %} ### **Get receive account by ID** You can fetch details of a particular receive user account linked to a receive user. #### `GET /users/{{user_id}}/receive-users/{{receive_user_id}}/accounts/{{receive_user_account_id}}` {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request GET '{{url}}/users/{{user_id}}/receive-users/{{receive_user_id}}/accounts/{{receive_user_account_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "account_number": "2662030406", "account_type": "SAVINGS", "bank_id": 40, "branch_id": 39, "created_at": "2022-01-14T11:17:54.287101", "id": "9db84704-fabc-4be2-b96b-f79f13809467", "payout_method": "BANK_DEPOSIT", "status": "UNVERIFIED", "user_id": "e2d1b7bf-4e8a-4e2d-b5a3-474525c396db", } ``` {% endtab %} {% endtabs %} # Payout Read on payout services available to you. ## Overview The section outlines the details of the payout services enabled for you. You can fetch enabled entities and locations along with the information required for payout. If you want additional payout corridors to be enabled for you, please let us know. # Get Banks Read on populating banks available for payout The bank and branch APIs provide the list of banks and their respective branches that are available in the destination country. ### Get bank list #### `GET /banks?country={{country}}` {% tabs %} {% tab title="Query Parameter" %} | **Name** | **Type** | **Required** | **Description** | | ------------ | -------- | ------------ | --------------------------------------------------------------------------------------------------------- | | country | String | No | [2-letter ISO code of the user’s country. ](https://www.nationsonline.org/oneworld/country_code_list.htm) | | {% endtab %} | | | | {% tab title="Request Sample" %} ``` curl --location --request GET '{{url}}/banks' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "branches": [ { "id": 169, "name": "Default Branch" } ], "country": "CO", "id": 126, "name": "Banco Santander De Negocios", "txn_supported_types": [ "C2C", "B2B", "B2C" ] }, { "branches": [ { "id": 101, "name": "Default Branch" } ], "country": "MX", "id": 58, "name": "All Banks / Payment Type: Clabe", "txn_supported_types": [ "C2C" ] } ``` {% endtab %} {% endtabs %} ### Get bank by ID #### `GET /banks/{{bankId}}` {% tabs %} {% tab title="Request Sample" %} ``` curl --location --request GET '{{url}}/banks/{bank_id}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "branches": [ { "id": 169, "name": "Default Branch" } ], "country": "CO", "id": 126, "name": "Banco Santander De Negocios", "receiving_currency": [ "COP" ], "txn_supported_types": [ "C2C", "B2B", "B2C" ] } ``` {% endtab %} {% endtabs %} # Get Payers Read on populating payers available for payout Payers are bill payment, cash pickup, and home delivery services in the destination country that is enabled for you. Based on the payer, there may be requirements for specific information and restrictions on payment amounts. For bill payment transactions, the details of each payer's services and information requirements can be obtained through the catalog. ### Get payer list #### `GET /payers?country={{Country}}&payout_method={{payout_method}}` For example, in order to get payers for Mexico, it will be {Country: MX or MEX} and for India, it will be {Country:IN or IND} and so on. {% tabs %} {% tab title="Request Sample" %} **Cash Pickup** ``` curl --location -g --request GET '{{url}}/payers?country=GH&delivery_method=CASH_PICKUP' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` **Wallet** ``` curl --location -g --request GET '{{url}}/payers?country=GH&delivery_method=WALLET' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} **Cash Pickup** ``` [ { "country": "GH", "delivery_method": "CASH_PICKUP", "id": 6, "name": "Express Union", "pickup_location": [] }, { "country": "GH", "delivery_method": "CASH_PICKUP", "id": 7, "name": "WARI", "pickup_location": [] }, { "country": "GH", "delivery_method": "CASH_PICKUP", "id": 8, "name": "Wizall", "pickup_location": [] }, { "country": "GH", "delivery_method": "CASH_PICKUP", "id": 9, "name": "Zeepay", "pickup_location": [] } ] ``` **Wallet** ``` [ { "country": "GH", "delivery_method": "WALLET", "id": 38, "name": "Airtel Money", "pickup_location": [] }, { "country": "GH", "delivery_method": "WALLET", "id": 39, "name": "MTN Mobile Money", "pickup_location": [] }, { "country": "GH", "delivery_method": "WALLET", "id": 40, "name": "Tigo Money", "pickup_location": [] }, { "country": "GH", "delivery_method": "WALLET", "id": 41, "name": "Vodafone Money", "pickup_location": [] } ] ``` {% endtab %} {% endtabs %} ### Get Payer by ID If you know the ID of the payer, you can use this endpoint to get the details of the specific payer. #### `GET /payers/{payerId}` {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request GET '{{url}}/payers/38' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "code": "Airtel Money", "country": "GH", "delivery_method": "WALLET", "id": 38, "name": "Airtel Money", "network_limit": [], "pickup_location": [], "receiving_currency": "GHS" } ``` {% endtab %} {% endtabs %} # Transaction (External) Read on creating and managing external transactions ## Overview Once you have the sender, funding account, and receiver details, you can continue to create a transaction to an external receiver. In general, the transactions created are external international transactions that are sent from a user in Machnet to an external receiver. There are different types of transactions and requirements for a transaction vary by type. Every transaction has two different flows: transaction processing(Debit) and delivery(Credit). The statuses of these two flows are different and updates on changes will be shared through webhooks. # Transaction Object Details on transaction object {% tabs %} {% tab title="Details" %}
FieldRequiredTypeDescription
idNoUUIDID of the transaction created.
user_idYesUUIDID of the User initiating the transaction.
from_fund_idYesUUIDAccount ID of the User from where the amount will be debited.
funding_source_typeYesStringEnumerated value: CARD, BANK_ACCOUNT
to.idYes UUIDID of the receive User who will receive the amount
to.fund_idYesUUIDID of the receive user’s fund.
to.payout_methodYesStringPayout method for transaction amount delivery. Enumerated Value: BANK_DEPOSIT (Default), CASH_PICKUP, WALLET, HOME_DELIVERY.
typeNoStringEnumerated value: TRANSFER|PAYOUT or PAYOUT
from_amountYesnumericThe amount entered by the user to be debited from the user’s account. We accept maximum two decimal places.
to_amountNonumericThe amount to be received by the receiving user. We accept maximum two decimal places.
from_currencyYesStringUser’s currency
to_currencyYesStringReceive user’s currency
exchange_rateYesnumericExchange rate used in transaction. We accept maximum four decimal places.
fee_amountYesnumericAdditional fee. We accept maximum two decimal places.
purposeYesCategoryThe purpose of sending money. Details below.
custom_purposeYes, if purpose is OTHERStringAdditional details when purpose is OTHER
physical_documentsNoObjectCopy of a document. This may be required for certain corridors and will be outlined in your spec sheet.
physical_documents.document_typeNoCategoryEnumerated value: INVOICE
physical_documents.document_valueNoStringValue of the document. Documents must be encoded Base64 before being uploaded to our system.
calculation_modeYesStringEnumerated value : SENDER_AMOUNT, RECEIVER_AMOUNT.
payer_idNonumericId of payer.
statusNoStringEnumerated value : INITIATED, PENDING, PROCESSING, PROCESSED, CANCELED, FAILED, HOLD, REFUNDED, RETURNED Note: Transaction hold reasons are listed below.
delivery_statusNoStringEnumerated Value : NONE, HOLD, PENDING, DELIVERY_REQUESTED, DELIVERED, DELIVERY_FAILED, DELIVERY_AUTHORIZED, DELIVERY_PAYOUT_READY
risk_scoreNonumericA Risk Score indicates the high or low risk of a transaction created by users. The lower the score, the less likely the event is high risk.
reference_numberNoStringA unique identification number of a transaction. This number is generated once the transaction is in PENDING status.
payout_reference_numberNoStringReference number provided by the payout partner.
bonus_amountNonumericBonus/discount provided on the transaction. The total amount deducted from the sender is equal to from_amount + fee_amount - bonus_amount. The nature of your implementation will determine whether a bonus or a discount is applied on the transaction. Please review use cases section for common implementation examples. We accept maximum two decimal places.
noteNoStringAdditional information on the transaction.
**Purpose** | **Purpose** | **Description** | | ------------------------ | ---------------------------------------------------- | | COMPUTER\_SERVICES | Computer service | | FAMILY\_SUPPORT | Family support | | EDUCATION | Education | | GIFT\_AND\_DONATION | Gift and other donations | | MEDICAL\_TREATMENT | Medical treatment | | MAINTENANCE\_EXPENSES | Maintenance or other expenses | | TRAVEL | Travel | | SMALL\_VALUE\_REMITTANCE | Small value remittance | | LIBERALIZED\_REMITTANCE | Liberalized remittance | | CONSTRUCTION\_EXPENSES | Construction expenses | | HOTEL\_ACCOMMODATION | Hotel accommodation | | ADVERTISING\_EXPENSES | Advertising and/or public relations related expenses | | ADVISORY\_FEES | Fees for advisory or consulting service | | BUSINESS\_INSURANCE | Business related insurance payment | | INSURANCE\_CLAIMS | Insurance claims payment | | DELIVERY\_FEES | Delivery fees | | EXPORTED\_GOODS | Payments for exported goods | | SERVICE\_CHARGES | Payment for services | | LOAN\_PAYMENT | Payment of loans | | OFFICE\_EXPENSES | Office expenses | | PROPERTY\_PURCHASE | Residential property purchase | | PROPERTY\_RENTAL | Property rental payment | | ROYALTY\_FEES | Royalty, trademark, patent and copyright fees | | SHARES\_INVESTMENT | Investment in shares | | FUND\_INVESTMENT | Fund investment | | TAX\_PAYMENT | Tax payment | | TRANSPORTATION\_FEES | Transportation fees | | UTILITY\_BILLS | Utility bills | | PERSONAL\_TRANSFER | Personal transfer | | SALARY\_PAYMENT | Payment of salary | | REWARD\_PAYMENT | Payment of rewards | | INFLUENCER\_PAYMENT | Payment of Influencer | | OTHER\_FEES | Broker, commitment, guarantee and other fees | | OTHER | Other purposes | | {% endtab %} | | | {% endtabs %} | | ### Transaction Hold Reasons {% hint style="info" %} Transactions may be placed on hold for specific reasons. Regardless of the reason, transactions on hold for more than 7 days are automatically cancelled. {% endhint %} | **Code** | **Reason** | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | T001 | Transaction is under review by compliance. Machnet will provide further information once available. | | T002 | Issue processing transaction. Please contact Machnet customer support. | | T003 | Unable to check balance of the funding account. Please contact Machnet customer support. | | T004 | Transaction limit based on the current tier of the user has been exceeded. If the user is eligible to increase their limits, requested information must be submitted and verified for the transaction to be processed. Check requested information using [this API](/api-references/user/get-verification-status). | | T005 | User is not verified. All basic information must be submitted and verified for the transaction to be processed. Check KYC status using [this API](/api-references/user/get-verification-status). | | T006 | Issue processing transaction. Please contact Machnet customer support. | | T007 | User is not verified. All basic information must be submitted and verified for the transaction to be processed. Check KYC status using [this API](/api-references/user/get-verification-status). | | T008 | Issue processing transaction. Please contact Machnet customer support. | | T009 | Issue processing transaction. Please contact Machnet customer support. | | T010 | Possible duplicate transaction. Please review. | | T011 | Unable to process the transaction. ACH authorization form may be required from the receiver. Please contact Machnet customer support. | | T012 | Unable to process the transaction. ACH authorization form may be required from the sender. Please contact Machnet customer support. | | T014 | Sender account is not verified. Please contact customer support for more details. | | T015 | Sender or sender’s account is not verified. Please contact customer support for more details | | T016 | Required sender information must be verified to process this transaction amount. | ### Transaction Cancellation Reason | | | | -------- | -------------------------------------------------------------------- | | **Code** | **Reason** | | C001 | Transaction risk is high. | | C002 | Platform limit exceeded. | | C003 | Transaction expired as it was on HOLD for more than 7 days | | C004 | Transaction was canceled by the user. | | C005 | Transaction was canceled by the admin. | | C006 | Transaction not authorized. Please contact Machnet customer support. | | C007 | Transaction not authorized. Please contact Machnet customer support. | | C008 | Transaction not authorized. Please contact Machnet customer support. | | C009 | Transaction not authorized. Please contact Machnet customer support. | | C010 | Transaction was canceled due to high risk of NSF. | | C011 | Transaction canceled as the user was suspended by admin. | {% hint style="info" %} We may add new transaction status, hold reasons and cancel reasons as and when required. The document will be updated accordingly. {% endhint %} # Create Transaction Read on how to create transactions in our system A transaction can be created only after the following criteria are fulfilled. * The Sender's KYC status is other than UNVERIFIED, IN PROGRESS, or SUSPENDED * At least one sender funding account has been linked by the sender and is active * At least one receive user has been added Based on the payout\_method, different information about the receive user and method is required. * payout\_method=`BANK_DEPOSIT`, funds are directly deposited into the receive user's account. Receive bank accounts need to be added for this transaction. * payout\_method=`WALLET`*,* funds are directly deposited to the receive user's wallet. Receive wallet accounts need to be added for this transaction. * payout\_method=`CASH_PICKUP`, funds can be collected at a cash pick-up location. The payer\_id of the relevant location must be specified for this transaction. * payout\_method=`HOME_DELIVERY`*,* funds are directly delivered to the receive user's home. Address must be accurate and payer\_id must be specified for the transaction. #### `POST /users/{{user_id}}/transactions` {% hint style="info" %} {% code overflow="wrap" %} ``` Supports Idempotency Key as part of header to avoid duplicate transaction. If you are creating a transaction with the same request and the same idempotency key again, the endpoint will consider this a duplicate request. It will not create a new transaction but will instead provide details of the initial transaction in the response. Response: 200 if a transaction is successfully created or transaction with the same idempotency key and request was created earlier 400 if the idempotency key is greater than 255 char 409 if the idempotency key is the same but the request is different ``` {% endcode %} {% endhint %} {% tabs %} {% tab title="Request Sample" %} **Bank Deposit** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: idempotencykey' \ --data-raw '{ "from_amount":1, "exchange_rate": 6.11, "to_amount":6.11, "fee_amount": 0, "note": "Sample Note", "to_currency":"USD", "from_currency":"USD", "custom_purpose":"home", "purpose": "OTHER", "physical_documents": [ { "document_type": "INVOICE", "document_value": "data:image/jpg;base64,SUQsasasasas909090==" } ], "ip_address": "10.10.10.5", "from_fund_id": UUID, "funding_source_type": "CARD", "to":{ "id": UUID, "fund_id" : UUID, "payout_method":"BANK_DEPOSIT", "calculation_mode":"SENDER_AMOUNT" } }' ``` **Wallet** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: idempotencykey' \ --data-raw '{ "from_amount":1, "exchange_rate": 6.11, "to_amount":6.11, "fee_amount": 0, "note": "Sample Note", "to_currency":"XAF", "from_currency":"USD", "remittance_purpose": "home payment", "ip_address": "10.10.10.5", "from_fund_id": UUID, "funding_source_type": "CARD", "purpose": "OTHER", "custom_purpose":"home", "physical_documents": [ { "document_type": "INVOICE", "document_value": "data:image/jpg;base64,SUQsasasasas909090==" } ], "to":{ "id": UUID, "fund_id" : UUID, "payout_method":"WALLET", "calculation_mode":"SENDER_AMOUNT", "payer_id" :42 } }' ``` **Cash Pickup** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount": 2.11, "exchange_rate": 1, "to_amount": 2.11, "fee_amount": 0, "note": "Sample Note", "to_currency": "GHS", "from_currency": "USD", "custom_purpose": "home", "purpose": "OTHER", "physical_documents": [ { "document_type": "INVOICE", "document_value": "data:image/jpg;base64,SUQsasasasas909090==" } ], "ip_address": "10.10.10.5", "from_fund_id": UUID, "funding_source_type": "CARD", "to": { "id": UUID, "payout_method": "CASH_PICKUP", "calculation_mode": "SENDER_AMOUNT", "payer_id": 9, "pickup_location": 1 } }' ``` {% endtab %} {% tab title="Response Sample" %} **Bank Deposit** ``` { "bonus_amount": 0, "created_at": "2022-05-18T11:48:05.127065", "custom_purpose": "home", "delivery_status": "NONE", "exchange_rate": 6.11, "fee_amount": 0, "from_amount": 1, "from_currency": "USD", "from_fund_id": UUID, "funding_source_type": "CARD", "id": UUID, "ip_address": "10.10.10.5", "note": "Sample Note", "physical_documents": [ { "document_type": "INVOICE", "id": UUID } ], "purpose": "OTHER", "status": "INITIATED", "to": { "address_line1": "500 El Camino Real Santa Clara", "calculation_mode": "SENDER_AMOUNT", "email": "norgayt@test.com", "first_name": "Tenzin", "fund_id": UUID, "id": UUID, "last_name": "Norgay", "mobile_phone": "2662030406", "payout_method": "BANK_DEPOSIT" }, "to_amount": 6.11, "to_currency": "USD", "user_id": UUID } ``` **Wallet** ``` { "bonus_amount": 0, "created_at": "2022-05-18T11:56:18.168841", "custom_purpose": "home", "delivery_status": "NONE", "exchange_rate": 6.11, "fee_amount": 0, "from_amount": 1, "from_currency": "USD", "from_fund_id": UUID, "funding_source_type": "CARD", "id": UUID, "ip_address": "10.10.10.5", "note": "Sample Note", "physical_documents": [ { "document_type": "INVOICE", "id": UUID } ], "purpose": "OTHER", "status": "INITIATED", "to": { "address_line1": "500 El Camino Real Santa Clara", "calculation_mode": "SENDER_AMOUNT", "email": "norgayt@test.com", "first_name": "Tenzin", "fund_id": UUID, "id": UUID, "last_name": "Norgay", "mobile_phone": "237676641000", "payout_method": "WALLET" }, "to_amount": 6.11, "to_currency": "XAF", "user_id": UUID } ``` **Cash Pickup** ``` { "bonus_amount": 0, "created_at": "2022-05-18T11:37:15.710741", "custom_purpose": "home", "delivery_status": "NONE", "exchange_rate": 1, "fee_amount": 0, "from_amount": 2.11, "from_currency": "USD", "from_fund_id": UUID, "funding_source_type": "CARD", "id": UUID, "ip_address": "10.10.10.5", "note": "Sample Note", "physical_documents": [ { "document_type": "INVOICE", "id": UUID } ], "purpose": "OTHER", "status": "INITIATED", "to": { "address_line1": "500 El Camino Real Santa Clara", "calculation_mode": "SENDER_AMOUNT", "email": "norgayt@test.com", "first_name": "Tenzin", "id": UUID, "last_name": "Norgay", "mobile_phone": "233541859101", "payer_id": 9, "payout_method": "CASH_PICKUP" }, "to_amount": 2.11, "to_currency": "GHS", "user_id": UUID } ``` {% endtab %} {% endtabs %} ### Calculation Mode There are two calculation models 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. ``` { "status": 400, "code": "BAD_REQUEST", "message": "From amount is not equivalent with To amount." } ``` For example, if the exchange rate today for USD to MEX, is 19.77 and the recipient\_amount is 427, the sender amount would be 427/19.66 = 21.719. Since our API will take the difference up to $0.01, $21.72 would be accepted for a successful transaction. # Get Transaction by ID Read on retrieving transaction related details You can fetch detailed information for a particular transaction of a user using the transaction ID. #### `GET /users/{{user_id}}/transactions/{{id}}` {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request GET '{{url}}/users/{{user_id}}/transactions/{{id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "bonus_amount": 0, "created_at": "2022-05-18T11:48:05.127065", "custom_purpose": "home", "delivery_status": "NONE", "exchange_rate": 6.11, "fee_amount": 0, "from_amount": 1, "from_currency": "USD", "from_fund_id": UUID, "funding_source_type": "CARD", "id": UUID, "ip_address": "10.10.10.5", "note": "Sample Note", "physical_documents": [ { "document_type": "INVOICE", "id": UUID } ], "purpose": "OTHER", "reference_number": "A003000007278", "status": "PROCESSED", "to": { "address_line1": "500 El Camino Real Santa Clara", "calculation_mode": "SENDER_AMOUNT", "email": "norgayt@test.com", "first_name": "Tenzin", "id": UUID, "last_name": "Norgay", "mobile_phone": "2662030406", "payout_method": "CASH_PICKUP" }, "to_amount": 6.11, "to_currency": "USD", "user_id": UUID } ``` {% endtab %} {% endtabs %} # Cancel Transaction Read on how to cancel transactions created in our system ACH transactions that have not been submitted for processing can be canceled using this API. You will receive appropriate error messages if a transaction cannot be canceled. **`DELETE /users/{{user_id}}/transactions/{{id}}`** {% tabs %} {% tab title="Request sample" %} ``` curl --location --request DELETE '{{url}}/users/{{user_id}}/transactions/{{id}}' \ --header 'X-Client-Id: 457dde89-76d4-41ac-97ee-f4a4321591d8' \ --header 'X-Client-Secret: c562435e-cb80-4df1-aa11-205a2df56b6a' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response sample" %} ``` Status code 200 OK ``` {% endtab %} {% endtabs %} # Transaction Delivery Read on how to request for and get status of delivery of a transaction ### Delivery Request Once the transaction has been created, you will need to request initialization of transaction delivery using this API. Delivery request can be initiated in the following scenarios: * Transaction Status is in PENDING or PROCESSED state * Transaction 'Type' is DEFAULT i.e. Not a REFUND transaction Until delivery is requested and approved, the transaction will not be forwarded for payout. #### `PATCH /users/{{user_id}}/transactions/delivery-requests/{{transaction_id}}` {% tabs %} {% tab title="Details" %} **Delivery Request Object** | | | | | | --------------- | ------------ | -------- | ----------------------------------------------------------- | | **Field** | **Required** | **Type** | **Description** | | status | Yes | String | Enumerated Value : DELIVERY\_REQUESTED | | comment | No | String | Comment / reason for requesting delivery | | transaction\_id | Yes | UUID | ID of the transaction for which delivery is being requested | | user\_id | Yes | UUID | ID of the user who created the transaction | | {% endtab %} | | | | {% tab title="Request sample" %} ``` curl --location -g --request PATCH '{{url}}/users/{{user_id}}/transactions/delivery-requests/{{transaction_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "status": "DELIVERY_REQUESTED", "comment": "string" }' ``` {% endtab %} {% tab title="Response sample" %} ``` Http status 204 (No Content) ``` {% endtab %} {% endtabs %} ### Delivery Status For clients using their own payout network to deliver a transaction, the status of the delivery needs to be updated on our system using this API. Statuses need to be updated to DELIVERED for completed transactions and DELIVERY\_FAILED for transactions which could not be completed. #### `POST /users/{{user_id}}/transactions/{{transaction_id}}/delivery-details` {% tabs %} {% tab title="Details" %} | | | | | | ----------------- | ------------ | -------- | ------------------------------------------------------------------------- | | **Field** | **Required** | **Type** | **Description** | | status | Yes | String | Enumerated Value : DELIVERED, DELIVERY\_FAILED | | transaction\_id | Yes | UUID | ID of transaction for which delivery status is being changed. | | user\_id | Yes | UUID | ID of the user who created the transaction | | date\_delivered | No | String | Date and time when the transaction was delivered (yyyy-mm-ddThh:mm:ss.ms) | | reference\_number | No | String | Client's reference number of the transaction | | {% endtab %} | | | | {% tab title="Request Sample" %} ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions/{{transaction_id}}/delivery-details --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "date_delivered" : "2022-12-21T22:28:22.261767", "status" : "DELIVERED", "reference_number" : 5657575 } ``` {% endtab %} {% tab title="Response Sample" %} ``` Http status 204 (No Content) ``` {% endtab %} {% endtabs %} # Get Transaction Limits You will be able to retrieve the remaining transaction limits of a particular user based on your spec sheet and transactions they have already created. #### `GET /users/{{user_id}}/transaction-limit?destination={{countryCode}}` {% tabs %} {% tab title="Details" %} | Field | Required | Type | Description | | ------------------------------- | -------- | ------- | ------------------------------------------------------------------- | | country | Response | String | 2-letter ISO code of the user’s country. | | current\_tier | Response | Numeric | Current tier of the user | | remaining\_limit | Response | Object | Remaining transaction limits of the user in the current tier | | remaining\_limit.annual\_limit | Response | Numeric | Remaining annual transaction limit of the user in the current tier | | remaining\_limit.monthly\_limit | Response | Numeric | Remaining monthly transaction limit of the user in the current tier | | remaining\_limit.daily\_limit | Response | Numeric | Remaining daily transaction limit of the user in the current tier | | user\_id | Response | UUID | UUID of the user | | {% endtab %} | | | | {% tab title="Request Sample" %} ``` curl --location --request GET '{{url}}/users/{{user_id}}/transaction-limit?destination='\''US'\''' \ --header 'X-Client-Id:{{client_id}} ' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "country": "US", "current_tier": 1, "remaining_limit": { "annual_limit": 9200.00, "daily_limit": 200, "monthly_limit": 4200.00 }, "user_id": "868a53c0-26b9-47d5-b79d-c7833842a681" } ``` {% endtab %} {% endtabs %} # Transaction (Wallet) Read on details creating different types of wallet transactions Wallets allow Clients to hold funds of the user in a designated user wallet. Clients must be approved for the wallet product in order to use it. Please contact Machnet team if you would like to use our wallet product for your use case. Wallet transfers allow users to send/receive funds to/from wallet funding source. You can add a wallet funding source for a user using [this API](/api-references/funds/create-a-wallet). Read more for details on creating transfers using wallet funding source. # Wallet Transfer Object ### Transfer Object Details | **Field** | **Required** | **Type** | **Description** | | -------------- | ------------ | -------- | ------------------------------------------------------------------------------------------ | | amount | Yes | String | Amount to be transferred | | fee\_amount | No | String | Fee that Clients want to charge for a transfer | | note | No | String | Note for amount transfer | | currency | Yes | String | Currency of the amount. USD for all wallet transfers | | from\_fund\_id | Conditional | String | ID of source funding account | | type | Yes | Category | Enum: LOAD, UNLOAD and TRANSFER | | to.id | Conditional | String | ID of receive user. This is only applicable for transfers of type TRANSFER | | to.fund\_id | Conditional | String | ID of receiving funding account | | ip\_address | Yes | String | IP of the user | | status | Response | String | Enum value: INITIATED, PENDING, PROCESSING, PROCESSED, CANCELED, FAILED, HOLD and RETURNED | ### Wallet Transfer Status Reasons | **Transfer** | **Reasons** | | ------------ | ---------------------------------------------------------------------------- | | Initiated | Transfer has been successfully created | | Pending | Transfers have been forwarded for processing | | Processing | Transfers are currently being processed | | Processed | Transfers have been successfully credited into the receiving funding account | | Failed | Transfer has failed. Please contact customer support | | Hold | Transfer is on hold. Please contact customer support | | Returned | Transfer has been returned. Please contact customer support | ### Hold Reasons in Transfer Response | **Code** | **Message** | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | T001 | Transaction is under review by compliance. Machnet will provide further information once available. | | T002 | Issue processing transaction. Please contact Machnet customer support. | | T003 | Unable to check balance of the funding account. Please contact Machnet customer support. | | T004 | Transaction limit based on the current tier of the user has been exceeded. If the user is eligible to increase their limits, requested information must be submitted and verified for the transaction to be processed. Check requested information using [this API](/api-references/user/get-verification-status). | | T005 | User verification is still in progress. All basic information must be submitted and verified for the transaction to be processed. Check KYC status using [this API](/api-references/user/get-verification-status). | | T006 | Issue processing transaction. Please contact Machnet customer support. | | T007 | User is not verified. All basic information must be submitted and verified for the transaction to be processed. | | T008 | Issue processing transaction. Please contact Machnet customer support. | | T009 | Issue processing transaction. Please contact Machnet customer support. | | T010 | Possible duplicate transaction. Please review. | | T011 | Unable to process the transaction. ACH authorization form may be required from the receiver. Please contact Machnet customer support. | | T012 | Unable to process the transaction. ACH authorization form may be required from the receiver. Please contact Machnet customer support. | | T013 | User’s maximum wallet limit exceeded. | | T014 | Sender’s account is not verified. Please contact customer support for more details | | TO15 | Sender or sender’s account is not verified. Please contact customer support for more details | | T016 | Required sender information must be verified to process this transaction amount. | ### Cancel Reasons in Transfer Response
Code Message
C001Transaction risk is high
C002Platform limit exceeded
C003Transaction expired as it was on HOLD for more than 7 days
C004Transaction was canceled by the user
C005Transaction was canceled by the admin
C006Transaction not authorized. Please contact Machnet customer support.
C007Transaction not authorized. Please contact Machnet customer support.
C008Transaction not authorized. Please contact Machnet customer support.
C009Transaction not authorized. Please contact Machnet customer support.
C010Transaction was canceled due to high risk of NSF.
C011Transaction canceled as the user was suspended by admin.
C013User’s maximum wallet limit exceeded.
C014Receiver’s maximum wallet limit exceeded.
C015Required recipient information must be verified to process this transaction amount.
{% hint style="info" %} We may add new Wallet Transfer Status, hold reasons and cancel reasons as and when required. The document will be updated accordingly. {% endhint %} # Create Transfers Wallet transfers allow users to create fund transfers from and to a user’s wallet. Wallet transfers are of three types: 1. Load: Users can load funds to a wallet account from their linked bank/card account. You can link bank/card accounts following details mentioned [here](/api-references/funds/funding-account-widget). 2. Unload: Users can withdraw funds from their wallet account to a linked bank/card account. You can link bank/card accounts following details mentioned [here](/api-references/funds/funding-account-widget). 3. Transfer: Users can send funds to another user's wallet within the same Client. The other wallet user must be verified and have a verified wallet account. # Load Wallet Read on details on loading funds into wallet account Users can load their wallet from their linked bank and card accounts. To do so, “type” must be specified as “LOAD” for load transfers. **`POST /users/{{userId}}/funds/{{wallet_id}}/transfers`** {% hint style="info" %} Supports Idempotency Key as part of header to avoid duplicate transaction. If you are creating a transaction with the same request and the same idempotency key again, the endpoint will consider this a duplicate request. It will not create a new transaction but will instead provide details of the initial transaction in the response. ​ **Response:** 200 if a transaction is successfully created or transaction with the same idempotency key and request was created earlier 400 if the idempotency key is greater than 255 char 409 if the idempotency key is the same but the request is different {% endhint %} {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request POST '{{url}}/users/{{userId}}/funds/{{wallet_id}}/transfers' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret:{{client_secret}} ' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: idempotencykey' \ --data-raw { "amount": 50, "fee_amount": 0, "note": "Sample Note", "currency": "USD", "ip_address": "10.10.10.5", "from_fund_id": "d71aa720-3948-4975-a2cd-f5ad977f2f02", "type": "LOAD" } ``` {% endtab %} {% tab title="Response Sample" %} ``` { "amount": 50, "currency": "USD", "fee_amount": 0, "from_fund_id": "bbee9d73-35d8-4ac0-8862-01bb89e6cadc", "id": "56a635be-48ea-48fa-a8c7-24b0c2cdbb30", "ip_address": "10.10.10.5", "note": "Sample Note", "status": "INITIATED", "to": { "fund_id": "ad82cebb-9ca3-4f2a-a1de-27f004b838bd", "id": "3e626447-cc80-4cd0-89e7-19001f939ee4" }, "type": "LOAD", "user_id": "3e626447-cc80-4cd0-89e7-19001f939ee4" } ``` {% endtab %} {% endtabs %} # Unload Wallet Read on details on unloading funds from wallet account Users can withdraw funds from their wallet account to their linked bank and card accounts. To do so, “type” must be specified as “UNLOAD” for unload transfers. **`POST /users/{{userId}}/funds/{{wallet_id}}/transfers`** {% hint style="info" %} Supports Idempotency Key as part of header to avoid duplicate transaction. If you are creating a transaction with the same request and the same idempotency key again, the endpoint will consider this a duplicate request. It will not create a new transaction but will instead provide details of the initial transaction in the response. ​ **Response:** 200 if a transaction is successfully created or transaction with the same idempotency key and request was created earlier 400 if the idempotency key is greater than 255 char 409 if the idempotency key is the same but the request is different {% endhint %} {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request POST '{{url}}/users/{{userId}}/funds/{{wallet_id}}/transfers' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret:{{client_secret}} ' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: idempotencykey' \ --data-raw { "amount": 5, "fee_amount": 0, "note": "Sample Note", "currency": "USD", "ip_address": "10.10.10.5", "type": "UNLOAD", "to": { "fund_id": "ad82cebb-9ca3-4f2a-a1de-27f004b838bd" } } ``` {% endtab %} {% tab title="Response Sample" %} ``` { "amount": 5, "currency": "USD", "fee_amount": 0, "from_fund_id": "ad82cebb-9ca3-4f2a-a1de-27f004b838bd", "id": "b3747713-b79f-412c-be42-3e2bf90e5c11", "ip_address": "10.10.10.5", "note": "Sample Note", "status": "INITIATED", "to": { "fund_id": "bbee9d73-35d8-4ac0-8862-01bb89e6cadc", "id": "3e626447-cc80-4cd0-89e7-19001f939ee4" }, "type": "UNLOAD", "user_id": "3e626447-cc80-4cd0-89e7-19001f939ee4" } ``` {% endtab %} {% endtabs %} # Wallet to Wallet Transfer Read on details on wallet to wallet transfer of funds Users can send funds to another user’s wallet within the same Client. To do so, in the request “type” must be specified as “TRANSFER”. **`POST /users/{{userId}}/funds/{{wallet_id}}/transfers`** {% hint style="info" %} Supports Idempotency Key as part of header to avoid duplicate transaction. If you are creating a transaction with the same request and the same idempotency key again, the endpoint will consider this a duplicate request. It will not create a new transaction but will instead provide details of the initial transaction in the response. ​ **Response:** 200 if a transaction is successfully created or transaction with the same idempotency key and request was created earlier 400 if the idempotency key is greater than 255 char 409 if the idempotency key is the same but the request is different {% endhint %} {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request POST '{{url}}/users/{{userId}}/funds/{{wallet_id}}/transfers' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret:{{client_secret}} ' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: idempotencykey' \ --data-raw{ "amount": 10, "fee_amount": 0, "note": "Sample Note", "currency": "USD", "ip_address": "10.10.10.5", "type": "TRANSFER", "to": { "id": "efdc93dd-4019-4f5a-84df-9cfc21d8ce2e", "fund_id": "bfdc93dd-4019-4f5a-84df-9cfc21d8ce2c" } } ``` {% endtab %} {% tab title="Response Sample" %} ``` { "amount": 4, "currency": "USD", "fee_amount": 0, "from_fund_id": "ad82cebb-9ca3-4f2a-a1de-27f004b838bd", "id": "6a74ab95-51b3-45f2-a0d9-d0236780a4de", "ip_address": "10.10.10.5", "note": "Sample Note", "status": "INITIATED", "to": { "fund_id": "9696d2f0-e15b-44cf-84ea-759c44a9b8c2", "id": "21000223-2561-44b7-a661-e06d8aa1bc3a" }, "type": "TRANSFER", "user_id": "3e626447-cc80-4cd0-89e7-19001f939ee4" } ``` {% endtab %} {% endtabs %} # Get Wallet Transfer Details Read on retrieving wallet transfer related details ### Get a particular wallet transfer's details You can fetch detailed information about a particular wallet transfer using the transfer ID. This will also include “status” which provides information on the transfer status. #### **`GET /users/{{userId}}/funds/{{wallet_id}}/transfers/{{transfer_id}}`** {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request GET '{{url}}/users/{{userId}}/funds/{{wallet_id}}/transfers/{{transfer_id}}' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret:{{client_secret}}' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "amount": 10.00, "currency": "USD", "fee_amount": 0.00, "from_fund_id": UUID, "id": UUID, "ip_address": "10.10.10.5", "note": "Sample Note", "status": "PROCESSED", "to": { "fund_id": UUID, "id": UUID }, "type": "TRANSFER", "user_id": UUID } ``` {% endtab %} {% endtabs %} ### Get list of all wallet transfers This API provides a list of all transfers loaded, unloaded and transferred from/to the wallet. #### **`GET /users/{{userId}}/funds/{{wallet_id}}/transfers`** {% tabs %} {% tab title="Request Sample" %} ``` curl --location -g --request GET ‘{{url}}/users/{{userId}}/funds/{{wallet_id}}/transfers' \ --header 'X-Client-Id: {{client_id}}' \ --header 'X-Client-Secret:{{client_secret}} ' ``` {% endtab %} {% tab title="Response Sample" %} ``` { "paging": { "page": 1, "page_size": 20, "total_count": 3 }, "results": [ { "amount": 10.00, "currency": "USD", "fee_amount": 0.00, "from_fund_id": UUID, "id": UUID, "ip_address": "10.10.10.5", "note": "Sample Note", "status": "PROCESSED", "to": { "fund_id": UUID, "id": UUID }, "type": "TRANSFER", "user_id": UUID }, { "amount": 10.00, "currency": "USD", "fee_amount": 0.00, "from_fund_id": UUID, "id": UUID, "ip_address": "10.10.10.5", "note": "Sample Note", "status": "PROCESSED", "to": { "fund_id": UUID, "id": UUID }, "type": "TRANSFER", "user_id": UUID }, { "amount": 50.00, "currency": "USD", "fee_amount": 0.00, "from_fund_id": UUID, "id": UUID, "ip_address": "10.10.10.5", "note": "Sample Note", "status": "PROCESSED", "to": { "fund_id": UUID, "id": UUID }, "type": "LOAD", "user_id": UUID } ] } ``` {% endtab %} {% endtabs %} # Get Limits Read on details on transaction limits specific to wallet accounts You will be able to retrieve the remaining transfer limits of a particular user's wallet based on your spec sheet and transactions they have already created. The transfer limits are categorized into the following transfer and transaction types: 1. Load: Adding funds into the wallet through linked card or bank. 2. Unload: Withdrawing funds from the wallet to linked card or bank. 3. Internal: Sending funds to another wallet holder. 4. External: Sending funds to external recipients using [transaction API](/api-references/transaction/create-1). This limit can also be obtained using the [Get Transaction limits API](/api-references/transaction/get-transaction-limits) but is only applicable for Clients who are approved for both wallet and external transactions. The remaining limits are also broken down into the following types: 1. Annual limit: Annual limit minus the amount already transfered this year. 2. Daily limit: Daily limit minus the amount already transfered today. 3. Monthly limit: Monthly limit minus the amount already transfered this month. 4. Wallet hold limit: Maximum wallet hold limit minus the actual balance of the wallet. This is particularly valid for LOAD transfer types as load amount shall not exceed remaining wallet hold limit. #### **`GET /users/{userId}/limits`** {% tabs %} {% tab title="Details" %} | Field | Required | Type | Description | | ------------------------------------ | -------- | ------- | ------------------------------------------------------------------- | | country | Response | String | 2-letter ISO code of the user’s country | | current\_tier | Response | Numeric | Current tier of the user | | remaining\_limit | Response | Object | Remaining transaction limit of the user in the current tier | | remaining\_limit.annual\_limit | Response | Numeric | Remaining annual transaction limit of the user in the current tier | | remaining\_limit.monthly\_limit | Response | Numeric | Remaining monthly transaction limit of the user in the current tier | | remaining\_limi.daily\_limit | Response | Numeric | Remaining daily transaction limit of the user in the current tier | | remaining\_limit.wallet\_hold\_limit | Response | Numeric | Remaining amount that can be held in the wallet | | user\_id | Response | UUID | UUID of the user | | type | Response | String | Transaction and transfer type for which the limits are applicable | | {% endtab %} | | | | {% tab title="Request Sample" %} ``` curl --location --request GET '{{url}}/users/{userId}/limits' \ --header 'X-Client-Id:{{client_id}} ' \ --header 'X-Client-Secret: {{client_secret}}' \ --header 'Content-Type: application/json' ``` {% endtab %} {% tab title="Response Sample" %} ``` [ { "country": "US", "remaining_limit": { "annual_limit": 10000, "daily_limit": 200, "monthly_limit": 5000 }, "type": "EXTERNAL", "current_tier" : 1, "user_id": UUID }, { "remaining_limit": { "annual_limit": 6401.00, "daily_limit": 1790.00, "monthly_limit": 2310.00, "wallet_hold_limit": 2000.00 }, "type": "LOAD", "current_tier" : 1, "user_id": UUID }, { "remaining_limit": { "annual_limit": 9860.80, "daily_limit": 22.00, "monthly_limit": 4960.80 }, "type": "UNLOAD", "current_tier" : 1, "user_id": UUID }, { "remaining_limit": { "annual_limit": 9876.60, "daily_limit": 200, "monthly_limit": 4906.60 }, "type": "TRANSFER", "current_tier" : 1, "user_id": UUID } ] ``` {% endtab %} {% endtabs %} # Transaction (Payout) Read for details on creating payout transactions Payout transactions allows Clients to disburse funds in multiple different countries. Clients must be approved for this service and the countries they would like to service. # Payout Transaction Object Details on transaction object for payout transactions
FieldRequiredTypeDescription
idNoUUIDID of the transaction created.
user_idYesUUIDClient ID for the transaction.
from.first_nameYesStringFirst name or entity name of the sender
from.middle_nameNoStringMiddle name of the sender
from.last_nameYes, if individualStringLast name of the sender
from.countryYesString2-letter ISO code of the sender country
from.zipcodeNoStringZip code of user
from.genderNoStringMale, Female, Other
from.date_of_birthYesStringBirth date of individual or Day of formation for business in yyyy-MM-dd format.
from.address_line1YesStringStreet address of the sender
from.cityYesStringCity of the sender
from.mobile_phoneYesNumeric10 digits mobile number of the individual or 10-15 digits phone number of the business.
from.emailYesStringEmail address of the sender
from.stateYesString2-letter ISO code of the sender’s state
from.mailingaddress.zipcodeYes, if businessStringZip code of the business
from.mailingaddress.countryYes, if businessString2-letter ISO code of the mailing country
from.mailingaddress.address_line1Yes, if businessStringAddress line 1 of the sender's mailing address
from.mailingaddress.cityYes, if businessStringCity of sender's mailing address
from.mailingaddress.stateNoStringState of sender's mailing address
from.physical_documentsYes, if businessObjectCopy of a sender's document. This may be required for individuals as well based on your spec sheet.
from.physical_documents.document_typeYes, if businessCategoryEnumerated value: CERTIFICATE_OF_INCORPORATION,EIN, PASSPORT, DRIVING_LICENCE, STATE_ID
from.physical_documents.document_valueYes, if businessStringCopy of document. Documents must be encoded Base64 before being uploaded to our system.
from.virtual_documentsYes, if businessObjectInformation of sender's document. This may be required for individuals as well based on your spec sheet.
from.virtual_documents.document_typeYes, if businessCategoryEnumerated value: EIN_NUMBER, PASSPORT, DRIVING_LICENCE, STATE_ID
from.virtual_documents.document_valueYes, if businessStringValue of the document.
to.payout_methodYesStringPayout method for transaction amount delivery. Enumerated Value: BANK_DEPOSIT (Default), CASH_PICKUP, WALLET
to.first_nameYesStringFirst name or entity name of receiver
to.last_nameYes, if individualStringLast name of receiver
to.mobile_numberYesNumber10 digits mobile number of the individual or 10-15 digits phone number of the business.
to.destination_countryYesString2-letter ISO code of receiver's country.
to.emailNoStringEmail address of the receiver. This field may be required based on your spec sheet.
to.address_line1YesStringStreet address of the receiver's residence if individual and registered address if business
to.address_line2NoStringStreet address of the receiver's residence if individual and registered address if business
to.cityNoStringReceiver's city of residence if individual and city of registration if business.
to.stateNoStringReceiver's state
to.zipcodeNoStringReceiver's zipcode
to.bank_idYes, if bank_depositNumberReceiver's bank ID
to.branch_idYes, if bank_depositNumberReceiver's branch ID
to.bank_nameYes, if bank_depositStringReceiver's bank name
to.account_numberYes, if bank_depositStringReceiver's bank account number
to.rtn_numberNoStringReceiver's routing number
to.payer_idYes, if cash_pickup and walletNumberID of payer associated with the wallet or cash pickup
to.pickup_location_idNoNumberLocation of the cash pickup agent
to.msisdnNoStringReceive user's wallet account number. (Default value if not provided for wallet payout method will be receiver's to.mobile_number)
to.wallet_typeNoCategoryType of receive user wallet. Enumerated value: TEL (Default value if not provided for wallet payout method will be TEL)
to.branch_locationNoStringReceiver bank branch location
to.virtual_documentYes, if businessObjectInformation of a receiver's identificiation document. Details will be outlined in your spec sheet.
to.virtual_document.document_typeYes, if businessCategoryEnumerated Value: EIN_NUMBER PASSPORT, DRIVING_LICENCE, STATE_ID
to.virtual_document.document_valueYes, if businessStringValue of the receiver's document. Documents must be encoded Base64 before being uploaded to our system.
from_amountYesNumericThe amount entered by the user to be debited from the user’s account. We accept maximum two decimal places.
physical_documentsNoObjectCopy of a document. This may be required for certain countries and will be outlined in your spec sheet.
physical_documents.document_typeNoCategoryEnumerated value: INVOICE
physical_documents.document_valueNoStringValue of the document. Documents must be encoded Base64 before being uploaded to our system.
to_amountNonumericThe amount to be received by the receiving user. We accept maximum two decimal places.
from_currencyYesStringUser’s currency
to_currencyYesStringReceive user’s currency
noteNoStringNote for transaction
exchange_rateYesnumericExchange rate used in transaction. We accept maximum four decimal places.
fee_amountYesnumericAdditional fee.
purposeYesCategoryThe purpose of sending money. Details below.
custom_purposeYes, if purpose is OTHERStringAdditional details when purpose is OTHER
calculation_modeNoStringEnumerated value : SENDER_AMOUNT, RECEIVER_AMOUNT.
ip_addressNoStringIP of the user
txn_typeNoStringEnumerated value: PAYOUT
transaction_statusNoStringEnumerated value : INITIATED, PENDING, PROCESSING, PROCESSED, CANCELED, FAILED, HOLD, REFUNDED, RETURNED Note: Transaction hold reasons are listed below.
delivery_statusNoStringEnumerated Value : NONE, HOLD, PENDING, DELIVERY_REQUESTED, DELIVERED, DELIVERY_FAILED, DELIVERY_AUTHORIZED, DELIVERY_PAYOUT_READY
risk_scoreNonumericA Risk Score indicates the high or low risk of a transaction created by users. The lower the score, the less likely the event is high risk.
reference_numberNoStringA unique identification number of a transaction. This number is generated once the transaction is in PENDING status.
payout_reference_numberNoStringReference number provided by the payout partner.
**Purpose** | **Purpose** | **Description** | | ------------------------ | ---------------------------------------------------- | | COMPUTER\_SERVICES | Computer service | | FAMILY\_SUPPORT | Family support | | EDUCATION | Education | | GIFT\_AND\_DONATION | Gift and other donations | | MEDICAL\_TREATMENT | Medical treatment | | MAINTENANCE\_EXPENSES | Maintenance or other expenses | | TRAVEL | Travel | | SMALL\_VALUE\_REMITTANCE | Small value remittance | | LIBERALIZED\_REMITTANCE | Liberalized remittance | | CONSTRUCTION\_EXPENSES | Construction expenses | | HOTEL\_ACCOMMODATION | Hotel accommodation | | ADVERTISING\_EXPENSES | Advertising and/or public relations related expenses | | ADVISORY\_FEES | Fees for advisory or consulting service | | BUSINESS\_INSURANCE | Business related insurance payment | | INSURANCE\_CLAIMS | Insurance claims payment | | DELIVERY\_FEES | Delivery fees | | EXPORTED\_GOODS | Payments for exported goods | | SERVICE\_CHARGES | Payment for services | | LOAN\_PAYMENT | Payment of loans | | OFFICE\_EXPENSES | Office expenses | | PROPERTY\_PURCHASE | Residential property purchase | | PROPERTY\_RENTAL | Property rental payment | | ROYALTY\_FEES | Royalty, trademark, patent and copyright fees | | SHARES\_INVESTMENT | Investment in shares | | FUND\_INVESTMENT | Fund investment | | TAX\_PAYMENT | Tax payment | | TRANSPORTATION\_FEES | Transportation fees | | UTILITY\_BILLS | Utility bills | | PERSONAL\_TRANSFER | Personal transfer | | SALARY\_PAYMENT | Payment of salary | | REWARD\_PAYMENT | Payment of rewards | | INFLUENCER\_PAYMENT | Payment of Influencer | | OTHER\_FEES | Broker, commitment, guarantee and other fees | | OTHER | Other purposes | ### Transaction Hold Reasons {% hint style="info" %} Transactions may be placed on hold for specific reasons. Regardless of the reason, transactions on hold for more than 7 days are automatically cancelled. {% endhint %} | **Code** | **Reason** | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | T001 | Transaction is under review by compliance. Machnet will provide further information once available. | | T002 | Issue processing transaction. Please contact Machnet customer support. | | T003 | Unable to check balance of the funding account. Please contact Machnet customer support. | | T004 | Transaction limit based on the current tier of the user has been exceeded. If the user is eligible to increase their limits, requested information must be submitted and verified for the transaction to be processed. Check requested information using [this API](/api-references/user/get-verification-status). | | T005 | User is not verified. All basic information must be submitted and verified for the transaction to be processed. Check KYC status using [this API](/api-references/user/get-verification-status). | | T006 | Issue processing transaction. Please contact Machnet customer support. | ### Transaction Cancellation Reason | | | | -------- | ---------------------------------------------------------- | | **Code** | **Reason** | | C001 | Transaction risk is high. | | C002 | Platform limit exceeded. | | C003 | Transaction expired as it was on HOLD for more than 7 days | | C004 | Transaction was canceled by the user. | | C005 | Transaction was canceled by the admin. | {% hint style="info" %} We may add new transaction status, hold reasons and cancel reasons as and when required. The document will be updated accordingly. {% endhint %} # Create Payout Transaction Read on how to create payout transactions in our system To create a payout transaction, you must specify`txn_type` as PAYOUT. Unlike other transaction types, sender and receiver details can be provided in the request body of the transaction API. A client that has been approved for Payout only service will need a specific `user_id` from Machnet which they will have to provide in the request body. #### `POST /users/{{user_id}}/transactions` {% tabs %} {% tab title="Request Sample" %} **Bank Deposit (C2C)** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount": 10, "exchange_rate": 3700, "to_amount": 37800, "fee_amount": 0, "note": "Sample Note", "to_currency": "COP", "from_currency": "USD", "custom_purpose": "home", "purpose": "OTHER", "txn_type":"PAYOUT", "ip_address": "10.10.10.5", "to": { "payout_method": "BANK_DEPOSIT", "branch_id": 153, “bank_id”:110, “bank_name”:”Digital Bank”, "address_line1": "500 El Camino Real Santa Clara", "first_name": "Pablolito", "last_name": "Doe", "mobile_phone": "233541859101", "email": "rkin@test.com", "account_type":"SAVINGS", "account_number":"2662030100", "rtn_number":"026009593", "destination_country": "CO", "city": "california", "country": "US", "state": "CA" }, "from": { "first_name": "first", "last_name":"last", "country": "US", "date_of_birth": "2000-01-01", "gender": "Male", "address_line1": "500 8 El Camino Real Santa Clara", "city": "california", "mobile_phone": "1234567890", "email": "em@email.com", "state": "CA" } }’ ``` **Bank Deposit (B2B)** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount": 100, "exchange_rate": 3700, "to_amount": 370000, "fee_amount": 0, "note": "Sample Note", "to_currency": "COP", "from_currency": "USD", "custom_purpose": "home", "purpose": "OTHER", "txn_type":"PAYOUT", "physical_documents": [ { "document_type": "INVOICE", "document_value": "data:image/jpg;base64,SUQs==" } ], "ip_address": "10.10.10.5", "to": { "payout_method": "BANK_DEPOSIT", "branch_id": 153, “bank_id”:110, “bank_name”:”Digital Bank”, "business":true, "address_line1": "500 El Camino Real Santa Clara", "first_name": "Pablolito", "last_name": "Doe", "mobile_phone": "233541859101", "email": "rkin@test.com", "account_type":"SAVINGS", "account_number":"2662030100", "rtn_number":"026009593", "destination_country": "CO", "city": "california", "country": "US", "state": "CA", "virtual_documents": [ { "document_type": "EIN_NUMBER", "document_value": "123456" } ] }, "from": { "first_name": "first", "country": "US", "business": true, "date_of_birth": "2000-01-01", "gender": "Male", "address_line1": "500 8 El Camino Real Santa Clara", "city": "california", "mobile_phone": "1234567890", "email": "em@email.com", "state": "CA", "physical_documents": [ { "document_type": "CERTIFICATE_OF_INCORPORATION", "document_value": "data:image/jpg;base64,SUQs==" }, { "document_type": "EIN", "document_value": "data:image/jpg;base64,SUQs==" } ], "virtual_documents": [ { "document_type": "EIN_NUMBER", "document_value": "123456" } ], "mailing_address": { "address_line1": "500 8 El Camino Real Santa Clara", "city": "california", "country": "US", "zipcode": 90305 } } }’ ``` **Bank Deposit (B2C)** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount": 100, "exchange_rate": 3700, "to_amount": 370000, "fee_amount": 0, "note": "Sample Note", "to_currency": "COP", "from_currency": "USD", "custom_purpose": "home", "purpose": "OTHER", "txn_type":"PAYOUT", "physical_documents": [ { "document_type": "INVOICE", "document_value": "data:image/jpg;base64,SUQs==" } ], "ip_address": "10.10.10.5", "to": { "payout_method": "BANK_DEPOSIT", "branch_id": 153, “bank_id”:110, “bank_name”:”Digital Bank”, "address_line1": "500 El Camino Real Santa Clara", "first_name": "Paolo", "last_name": "Sharma", "mobile_phone": "233541859101", "email": "rkin@test.com", "account_type":"SAVINGS", "account_number":"2662030100", "rtn_number":"026009593", "destination_country": "CO", "city": "california", "state": "CA" }, "from": { "first_name": "Machnet", "country": "US", "business": true, "date_of_birth": "2000-01-01", "gender": "Male", "address_line1": "500 8 El Camino Real Santa Clara", "city": "california", "mobile_phone": "237676641000", "email": "em@email.com", "state": "CA", "physical_documents": [ { "document_type": "CERTIFICATE_OF_INCORPORATION", "document_value": "data:image/jpg;base64,SUQs==" }, { "document_type": "EIN", "document_value": "data:image/jpg;base64,SUQs==" } ], "virtual_documents": [ { "document_type": "EIN_NUMBER", "document_value": "123456" } ], "mailing_address": { "address_line1": "500 8 El Camino Real Santa Clara", "city": "california", "country": "US", "zipcode": 90305 } } }’ ``` **Wallet** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount": 2.01, "exchange_rate": 1, "to_amount": 2.01, "fee_amount": 0, "note": "Sample Note", "to_currency": "GHS", "from_currency": "USD", "purpose": "FAMILY_SUPPORT", "ip_address": "10.10.10.5", "txn_type": "PAYOUT", "to": { "payout_method": "WALLET", "payer_id": 39, "address_line1": "500 El Camino Real Santa Clara", "first_name": "Mahendra", "last_name": "Doe", "mobile_phone": "263775892100", "email": "rkin@test.com", "destination_country": "GH" }, "from": { "first_name": "first", "last_name": "last", "country": "US", "date_of_birth": "2000-01-01", "gender": "Male", "address_line1": "500 8 El Camino Real Santa Clara", "city": "california", "mobile_phone": "1234567890", "email": "em@email.com", "state": "CA" } }’ ``` **Cash Pickup** ``` curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \ --header 'X-Client-Id: client_id' \ --header 'X-Client-Secret: client_secret' \ --header 'Content-Type: application/json' \ --data-raw '{ "from_amount": 21.1, "exchange_rate": 1, "to_amount": 21.1, "fee_amount": 0, "note": "Sample Note", "to_currency": "GHS", "from_currency": "USD", "purpose": "EDUCATION", "ip_address": "10.10.10.5", "txn_type": "PAYOUT", "to": { "payout_method": "CASH_PICKUP", "payer_id": 9, "address_line1": "Sekondi-Takoradi", "first_name": "Paololito", "last_name": "Doe", "mobile_phone": "233541859100", "email": "rkin@test.com", "destination_country": "GH" }, "from": { "first_name": "first", "last_name": "last", "country": "US", "date_of_birth": "2000-01-01", "gender": "Male", "address_line1": "500 8 El Camino Real Santa Clara", "city": "california", "mobile_phone": "1234567890", "email": "em@email.com", "state": "CA" } }' ``` {% endtab %} {% tab title="Response Sample" %} **Bank Deposit (C2C)** ``` { "bonus_amount": 0, "created_at": "2022-07-29T10:59:05.359647", "custom_purpose": "home", "delivery_status": "NONE", "exchange_rate": 3700, "fee_amount": 0, "from": { "address_line1": "500 8 El Camino Real Santa Clara", "business": false, "city": "california", "country": "US", "date_of_birth": "2000-01-01", "email": "em@email.com", "first_name": "first", "gender": "Male", "last_name": "last", "mobile_phone": "1234567890", "physical_documents": [], "state": "CA", "virtual_documents": [] }, "from_amount": 10, "from_currency": "USD", "id": "0955e835-e1e5-46eb-881d-dde8dadc2c58", "ip_address": "10.10.10.5", "note": "Sample Note", "physical_documents": [], "purpose": "OTHER", "status": "NONE", "to": { "account_number": "2662030100", "account_type": "SAVINGS", "address_line1": "500 El Camino Real Santa Clara", "branch_id": "153", “bank_id”:110, “bank_name”:”Digital Bank”, "business": false, "calculation_mode": "SENDER_AMOUNT", "city": "california", "destination_country": "CO", "email": "rkin@test.com", "first_name": "Pablolito", "last_name": "Doe", "mobile_phone": "233541859101", "payout_method": "BANK_DEPOSIT", "rtn_number": "026009593", "state": "CA", "virtual_documents": [] }, "to_amount": 37000, "to_currency": "COP", "user_id": "19c1a9ed-e3db-4293-b2c2-48c59fe8e199" } ``` **Bank Deposit (B2B)** ``` { "bonus_amount": 0, "created_at": "2022-07-29T10:57:23.392928", "custom_purpose": "home", "delivery_status": "NONE", "exchange_rate": 3700, "fee_amount": 0, "from": { "address_line1": "500 8 El Camino Real Santa Clara", "business": true, "city": "california", "country": "US", "date_of_birth": "2000-01-01", "email": "em@email.com", "first_name": "first", "gender": "Male", "mailing_address": { "address_line1": "500 8 El Camino Real Santa Clara", "city": "california", "country": "US", "zipcode": "90305" }, "mobile_phone": "1234567890", "physical_documents": [ { "document_type": "CERTIFICATE_OF_INCORPORATION", "id": "2f081250-89eb-4fba-9a82-cc29e0e707b1" }, { "document_type": "EIN", "id": "95a875fd-d175-44c1-a66f-073397bbeb92" } ], "state": "CA", "virtual_documents": [ { "document_type": "EIN_NUMBER", "document_value": "123456", "id": "b8bfbc92-22dd-477d-9249-2004d6bedf1f" } ] }, "from_amount": 100, "from_currency": "USD", "id": "748a6fd9-7269-4fbd-a177-cffa13bb3014", "ip_address": "10.10.10.5", "note": "Sample Note", "physical_documents": [ { "document_type": "INVOICE", "id": "68bb6f18-6276-41a4-b9bd-41391cb0c4d5" } ], "purpose": "OTHER", "status": "NONE", "to": { "account_number": "2662030100", "account_type": "SAVINGS", "address_line1": "500 El Camino Real Santa Clara", "branch_id": "153", “bank_id”:110, “bank_name”:”Digital Bank”, "business": true, "calculation_mode": "SENDER_AMOUNT", "city": "california", "destination_country": "CO", "email": "rkin@test.com", "first_name": "Pablolito", "last_name": "Doe", "mobile_phone": "233541859101", "payout_method": "BANK_DEPOSIT", "rtn_number": "026009593", "state": "CA", "virtual_documents": [ { "document_type": "EIN_NUMBER", "document_value": "123456", "id": "b8bfbc92-22dd-477d-9249-2004d6bedf1f" } ] }, "to_amount": 370000, "to_currency": "COP", "user_id": "fdb20851-e27e-4653-9346-81f04a8cafd4" } ``` **Bank Deposit (B2C)** ``` { "bonus_amount": 0, "created_at": "2022-07-29T10:58:29.932733", "custom_purpose": "home", "delivery_status": "NONE", "exchange_rate": 3700, "fee_amount": 0, "from": { "address_line1": "500 8 El Camino Real Santa Clara", "business": true, "city": "california", "country": "US", "date_of_birth": "2000-01-01", "email": "em@email.com", "first_name": "Machnet", "gender": "Male", "mailing_address": { "address_line1": "500 8 El Camino Real Santa Clara", "city": "california", "country": "US", "zipcode": "90305" }, "mobile_phone": "237676641000", "physical_documents": [ { "document_type": "CERTIFICATE_OF_INCORPORATION", "id": "2c0302fe-ee45-4e30-94f5-927ac2d70119" }, { "document_type": "EIN", "id": "e286639d-ad27-44bb-882d-d20648cadf2d" } ], "state": "CA", "virtual_documents": [ { "document_type": "EIN_NUMBER", "document_value": "123456", "id": "b8bfbc92-22dd-477d-9249-2004d6bedf1f" } ] }, "from_amount": 100, "from_currency": "USD", "id": "d674d919-ac80-4564-811d-4ae0c95c5d34", "ip_address": "10.10.10.5", "note": "Sample Note", "physical_documents": [ { "document_type": "INVOICE", "id": "2892d026-abaf-4cda-bbfe-8cf93b808250" } ], "purpose": "OTHER", "status": "NONE", "to": { "account_number": "2662030100", "account_type": "SAVINGS", "address_line1": "500 El Camino Real Santa Clara", "branch_id": "153", “bank_id”:110, “bank_name”:”Digital Bank”, "business": false, "calculation_mode": "SENDER_AMOUNT", "city": "california", "destination_country": "CO", "email": "rkin@test.com", "first_name": "Paolo", "last_name": "Sharma", "mobile_phone": "233541859101", "payout_method": "BANK_DEPOSIT", "rtn_number": "026009593", "state": "CA", "virtual_documents": [] }, "to_amount": 370000, "to_currency": "COP", "user_id": "19c1a9ed-e3db-4293-b2c2-48c59fe8e199" } ``` **Wallet** ``` { "bonus_amount": 0, "created_at": "2022-07-29T10:56:16.326256", "delivery_status": "NONE", "exchange_rate": 1, "fee_amount": 0, "from": { "address_line1": "500 8 El Camino Real Santa Clara", "business": false, "city": "california", "country": "US", "date_of_birth": "2000-01-01", "email": "em@email.com", "first_name": "first", "gender": "Male", "last_name": "last", "mobile_phone": "1234567890", "physical_documents": [], "state": "CA", "virtual_documents": [] }, "from_amount": 2.01, "from_currency": "USD", "id": "3379 cfcb-fb73-43c1-8670-60a448914787", "ip_address": "10.10.10.5", "note": "Sample Note", "physical_documents": [], "purpose": "FAMILY_SUPPORT", "status": "NONE", "to": { "address_line1": "500 El Camino Real Santa Clara", "business": false, "calculation_mode": "SENDER_AMOUNT", "destination_country": "GH", "email": "rkin@test.com", "first_name": "Mahendra", "last_name": "Doe", "mobile_phone": "263775892100", "payer_id": 39, "payout_method": "WALLET", "virtual_documents": [] }, "to_amount": 2.01, "to_currency": "GHS", "user_id": "19c1a9ed-e3db-4293-b2c2-48c59fe8e199" } ``` **Cash Pickup** ``` { "bonus_amount": 0, "created_at": "2022-07-29T10:55:08.422724", "delivery_status": "NONE", "exchange_rate": 1, "fee_amount": 0, "from": { "address_line1": "500 8 El Camino Real Santa Clara", "business": false, "city": "california", "country": "US", "date_of_birth": "2000-01-01", "email": "em@email.com", "first_name": "first", "gender": "Male", "last_name": "last", "mobile_phone": "1234567890", "physical_documents": [], "state": "CA", "virtual_documents": [] }, "from_amount": 21.1, "from_currency": "USD", "id": "91516ee8-c6e1-4549-aad6-04f9d3930bff", "ip_address": "10.10.10.5", "note": "Sample Note", "physical_documents": [], "purpose": "EDUCATION", "status": "NONE", "to": { "address_line1": "Sekondi-Takoradi", "business": false, "calculation_mode": "SENDER_AMOUNT", "destination_country": "GH", "email": "rkin@test.com", "first_name": "Paololito", "last_name": "Doe", "mobile_phone": "233541859100", "payer_id": 9, "payout_method": "CASH_PICKUP", "virtual_documents": [] }, "to_amount": 21.1, "to_currency": "GHS", "user_id": "19c1a9ed-e3db-4293-b2c2-48c59fe8e199" } ``` {% endtab %} {% endtabs %} # Webhooks Read for details on using our webhooks for updates ## Overview When the state of a resource change, our 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. # Subscribe Read on how to get our webhooks 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. #### `POST /subscriptions` {% tabs %} {% tab title="Request sample" %} ``` curl --location -g --request POST '{{url}}/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" }' ``` {% endtab %} {% tab title="Response sample" %} ``` [ { "end_point": "url", "secret": "UUID", "active_from": "2021-03-10 05:49:51", "id": "UUID", "is_active": true, "is_paused": false } ] ``` {% endtab %} {% endtabs %} # Integration Read on how to deal with our webhooks After the Subscription API has been set up, webhooks are ready to use. Webhooks will be fired from our end when any listed event is triggered. We will trigger a POST request to the URL provided on the Subscription API. **Webhook 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 | **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. User 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. | | user\_id | If user related resources are triggered as part of an event then user\_id will be sent as part of the payload. | | subscription\_id | Subscription Id for which this event was generated. | | payload | In case of a cip tag status event, this contains a list of cip tags for which the status has been updated. | | timestamp | Timestamp when the webhook is posted. | **Responding to Webhooks** When you receive the webhook events, you can respond back with the 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. |
# Events Read on when webhooks are sent from our system ## **KYC events** | | | | | | --------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | **KYC Status** | **Events** | **Description** | **Occurance** | | IN\_PROGRESS | user\_kyc\_in\_progress | User's KYC is in progress. | Queued for running KYC after ‘initiate KYC’ API is called | | VERIFIED | user\_kyc\_verified | User’s KYC is complete and user details are verified. | User KYC is successfully complete. | | RETRY | user\_kyc\_retry | If user KYC is not complete and additional details have to be provided. Once the details have been collected, ‘Initiate KYC’ API needs to be called again. | After the ‘initiate KYC’ API is called and user status is not VERIFIED. | | SUSPENDED | user\_kyc\_suspended | When a user's KYC is rejected during KYC process. | | | REVIEW\_PENDING | user\_kyc\_review\_pending | When a user’s KYC process is in review state. |


| ## **Transaction events** | **Transaction Status** | **Event** | **Description** | | ---------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- | | INITIATED | No Webhook | The transaction request has been submitted in our system. | | PENDING | transaction\_created | The transaction is undergoing compliance check or has been selected for processing. | | PROCESSING | transaction\_processing | The transaction is being processed. | | PROCESSED | transaction\_processed | The transaction has been processed successfully. | | FAILED | transaction\_failed | The transaction was unable to be processed. | | HOLD | transaction\_onhold | When the user’s transaction is on hold. The hold reason is provided in the response when fetching transaction information. | | CANCELED | transaction\_canceled | The transaction was cancelled by the user or admin. | | RETURNED | transaction\_returned | Transaction has been returned. | | REFUNDED | transaction\_refunded | Transaction has been successfully refunded to the sender. | ## **Delivery events** | **Delivery Status** | **Event** | **Description** | | ----------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | NONE | No webhook | Initial status. Transaction delivery has not been requested or transaction has not been forwarded for delivery. | | PENDING | transaction\_delivery\_pending | Transaction has been forwarded for delivery. | | DELIVERY\_REQUESTED | transaction\_delivery\_requested | Client has requested delivery of the transaction. | | HOLD | transaction\_delivery\_onhold | Delivery of transaction has been placed on hold. | | DELIVERY\_FAILED | transaction\_delivery\_failed | Transaction could not be delivered. | | DELIVERY\_PAYOUT\_READY | transaction\_delivery\_payout\_ready | Only relevant for cash pick up transactions. Recipients can go pick up cash from the designated location when it is delivery payout ready. | | DELIVERED | transaction\_delivered | Transaction has been successfully delivered/paid out to the recipient. | | DELIVERY\_AUTHORIZED | transaction\_delivery\_authorized | Transaction delivery is authorized. If you are paying out transactions yourself as per agreement with Machnet, you can now proceed to delivery the transaction to the recipient. | | DELIVERY\_CANCELED | transaction\_delivery\_canceled | When transaction is cancelled, transaction delivery is automatically cancelled too. | ## **Funding account events** | **Event** | **Description** | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | user\_card\_added | User’s card account has been successfully added. | | user\_card\_removed | User’s card account has been successfully removed. | | user\_bank\_verification\_pending | User’s bank account has been added but verification status is “PENDING”. User can create a transaction using the funding account but it will not be processed until the account is verified. | | user\_bank\_added | User’s bank account has been successfully added and the account has been verified. | | user\_bank\_removed | User’s bank account has been successfully removed either through the widget or using API. | | user\_bank\_verification\_failed | User's bank account verification failed and it is locked. User cannot use this bank account to create a transaction. | | bank\_login\_required | User needs to re-login to their account. You will have to open the bank widget again with the particular funding account ID and ask user to login to their bank again. | ## **Widget events** | Event | Description | | ----------- | ---------------------------------------------------------------- | | BANK\_ERROR | Error while adding bank using widget. Please try again. | | CARD\_ERROR | Error while adding card using widget. Please try again. | | BANK\_ADDED | Bank successfully added but account verification may be pending. | ## **CIP tag status events** | Event | Description | | ------------------- | ------------------------------------------------------------------------------------------------------ | | cip\_tag\_submitted | User information has been successfully submitted. | | cip\_tag\_reviewing | User information is under review. The status of this CIP tag will be updated once review is completed. | | cip\_tag\_verified | User information has been successfully verified | | cip\_tag\_failed | User information verification has failed | | cip\_tag\_requested | User information has been requested. Please ask the user to submit this information. | # Error Codes | **Error Code** | **Description** | | -------------- | ----------------------------------------------------------------------------------------- | | 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. | # User: Test Values Sample values for Sandbox ### **SSN** | Value | Status | | ---------------------------------------------------------------------------------------------- | -------- | |

document\_value: 222222222

document\_type: SSN

country: US

state: Ak

| Verified | # Funds: Test Values Sample values for Sandbox ### **Card addition**
Funding SourceNetworkPermissionCard Number
CARDVISADEBIT9401110999999991
CARDVISACREDIT-AND-DEBIT9401113999999995
CARDMASTERCARDDEBIT9501110999999990
### **Bank login credentials (Chatbot)** | Username | Password | MFA | | ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `test_good` | `test1234` |

again For multiple MFAs.
test\_answerFor single MFA.
Bank Name: fake

| | `synapse_good` | `test1234` |

again For multiple MFAs.
test\_answerFor single MFA.
Bank Name: fake

| | `synapse_nomfa` | `test1234` | No MFA necessary | | `synapse_code_mfa` | `test1234` | `123456` Bank Name: `fake` | | `synapse_good` | `test1234_checking` |

again For multiple MFAs.
test\_answerFor single MFA.
Bank Name: fake

| ### **Bank login credentials (MX): Non-OAuth** | **Username** | **Password** | **Description** | | ------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | mxuser | Any value not described below. | Successful bank addition with no MFA. | | mxuser | `challenge` | Issues an MFA challenge. Answer with correct to simulate a correct MFA response, or use one of the passwords below that simulate a server error. Use anything else to simulate an incorrect answer. | | mxuser | `BAD_REQUEST` | External server returns a 400 error with the message, “You must fill out the username and password fields.” | | mxuser | `UNAUTHORIZED` | External server returns a 401 error with the message, “Invalid credentials.” | ### **Bank login credentials (MX):** OAuth | | | | --------------- | ------------------------------------------------------------------------------ | | **Bank Name** | **Description** | | MX Bank (OAuth) | Select the OAuth bank from the bank dropdown list and follow the instructions. | # Transaction: Test Values Sample values for Sandbox ### Cash pickup | Country | payer | Receive user MSISDN | | -------- | ------------- | ------------------- | | Cameroon | Express Union | 237676641000 | | Ghana | Zeepay | 233541859101 | ### Wallet | Country | Operator | MSISDN | | ------- | --------- | --------------------------------------------------------------------------------------------------- | | Ghana | MTN Ghana |

233242516556
233244474572
233244674986
233247547888
233543225243
233242541281

| # 2023 Review this log for all the changes in our APIs and docs in 2023 ## Overview We document all changes in our APIs and subsequent changes in our API docs in this section. Please refer to them periodically to ensure that your systems are also up-to-date. If you have any questions, feel free to contact us at . # February 14, 2023 ## New * New wallet product to hold business user's funds. Users can load, unload and transfer funds from their wallet as well as use wallet funds to create transactions to external receivers. Flow and integration guidelines can be found [here](/use-cases/business-wallet). You will need to be approved for this product by Machnet to be able to access the APIs. All APIs (Business user, Business Representative, Declaration, Receive user) associated with this product have been updated. * Additional hold reasons have been added for [external](/api-references/transaction/create#transaction-hold-reasons) and [wallet](/api-references/transaction-wallet/wallet-transfer-object#hold-reasons-in-transfer-response) transactions. * New instant account verification using MX has been released. This will also use our existing [bank widget](/api-references/funds/funding-account-widget). However, there are additional [OAuth flows](/api-references/funds/funding-account-widget/oauth-integration) and [bank verification statuses](/api-references/funds/funding-account-widget/bank-verification-status) that need to be considered. Our legacy instant account verification using chatbot will be deprecated soon. This new integration must be enabled for you before you can integrate and test it out. The new test values are also listed [here](/test-values/sandbox-1#bank-login-credentials-mx-non-oauth). Please contact Machnet for additional details. ## Updates * Updates in business user's basic information. Details can be found in [Business Payments](/use-cases/business-payments) and [User Verification](/api-references/user/registration/user-verification). * Added object details for [Get Transaction Limits](/api-references/transaction/get-transaction-limits) and [Get Limits API](/api-references/transaction-wallet/get-limits) * Added [funding account widget events ](/api-references/webhooks/events#widget-events) * Fixed errors in [update user](/api-references/user/user-kyc), [receive user](/api-references/user/update-a-receive-user) and [business representative](/api-references/user/business-representatives/update-business-representatives) API docs # January 06, 2023 ## New Features * Added new hold and cancellation reasons for [Wallet Transfer Object](/api-references/transaction-wallet/wallet-transfer-object) * Added new hold reason for [Transaction Object](/api-references/transaction/create) # 2022 Review this log for all the changes in our APIs and docs in 2022 ## Overview We document all changes in our APIs and subsequent changes in our API docs in this section. Please refer to them periodically to ensure that your systems are also up-to-date. If you have any questions, feel free to contact us at . # December 28, 2022 ## Updates Features * Additional information have been included on [User verification](/api-references/user/registration/user-verification) including [KYC/KYB statuses](/api-references/user/registration/user-verification-status) and [CIP information status](/api-references/user/registration/cip-information-status). # December 26, 2022 ## New Features * New wallet product to hold individual user's funds. Users can load, unload and transfer funds from their wallet as well as use wallet funds to create transactions to external receivers. Common integration guidelines can be found [here](/use-cases/individual-wallet). You will need to be approved for this product by Machnet to be able to access the APIs. ## Updates Features * Transaction API section has been restructured to differentiate between [External](/api-references/transaction), [Wallet](/api-references/transaction-wallet) and [Payout](/api-references/transaction-payout) products. You can visit the [use case](/use-cases/remittance) section to review the APIs required for your particular use case or contact Machnet for further clarification. # December 23, 2022 ## New Features * `user_bank_verification_pending` [webhook event has been added](/api-references/webhooks/events#funding-account-events) * Support idempotency key as part of [Create transaction API](/api-references/transaction/create-1), [Create Transfer API ](/api-references/transaction-wallet/create-transfers)and [Create Payout Transaction API](/api-references/transaction-payout/create-1) ## Updated Features * Updated `date_delivered` field format to yyyy-mm-ddThh:mm:ss.ms in [Transaction delivery status API](/api-references/transaction/transaction-delivery#delivery-status) for Clients paying out transactions by themselves # December 2, 2022 ## New Features * Added [Individual Wallet Object](/api-references/funds/wallet-object) details * Added [Add an Individual Wallet](/api-references/funds/create-a-wallet) page * Added [Get Wallet Details](/api-references/funds/get-wallet-details) page * Added [Wallet Transaction](/api-references/transaction-wallet) section with subpages * Added [Get Wallet Transaction By ID](/api-references/transaction-wallet/get-wallet-transfer-details) and [Transaction List](broken://pages/0dy9BofUv3ARd7MIErL7) pages * Added [Get Wallet Transaction Limits](/api-references/transaction-wallet/get-limits) page ## Updated Features * Updated response of [Spec sheet API](/api-references/data-population/spec-sheet) based on configured products for a Client # November 21, 2022 ## New Features * Added webhook for [transaction\_delivery\_canceled](/api-references/webhooks/events#delivery-events) * Added web hook for [bank\_error](/api-references/webhooks/events#funding-account-events) and [card\_error](/api-references/webhooks/events#funding-account-events) * Added webhook for [bank\_login\_required](/api-references/webhooks/events#funding-account-events) * Added `current_tier` field in [Get transaction limits API](/api-references/transaction/get-transaction-limits) to show the current tier level of a user # November 11, 2022 ## Updated Features * Added [transaction\_refunded](/api-references/webhooks/events#transaction-events) webhook to notify when transaction refunds are initiated. # October 31, 2022 ## Update Features * Added `bonus_amount` field in [Create Transaction API](/api-references/transaction/create). This field can be used to provide bonus or discount on a [user's transaction](/api-references/transaction/create-1). If no value is provided for the field, 0 bonus/discount will be applied. [Integration details and examples are provided here. ](/use-cases/remittance/bonus-discount-on-remittance) # October 17, 2022 ## New Features * Added new product: [Payout ](/use-cases/payout) ## Update Features * [Updating receive user information](/api-references/user/update-a-receive-user) * [Updating receive user account information](/api-references/funds/update-a-receive-account) # August 31, 2022 ## Updated Features * Added 'OTHER' enum value for `physical_documents.document_type` and `virtual_documents.document_type` of [receive users](/api-references/user/add-a-receive-user#receive-user-object-details) to submit documents apart from the ones listed * Added `physical_documents.custom_document_type` and `virtual_documents.custom_document_type` fields to submit specific document type value when `physical_documents.document_type` and virtual\_documents.document\_type is 'OTHER' for [receive users](/api-references/user/add-a-receive-user#receive-user-object-details) * Updated `to_amount`, `from_amount` and `exchange_rate` fields to only accept maximum 2 decimal places while [creating transactions](/api-references/transaction/create-1#details) # August 1, 2022 ## Updated Features * Added [transaction cancellation reasons](/api-references/transaction/create-1#transaction-cancellation-reason) * Added parameters to [webhook requests](/api-references/webhooks/integration) * Added object details for transaction [delivery request API](/api-references/transaction/transaction-delivery#delivery-request) and [delivery status API](/api-references/transaction/transaction-delivery#change-delivery-status) * `funding_source_type` added to response of [create transaction](/api-references/transaction/create-1) and [get transaction by ID API](/api-references/transaction/get-transaction-by-id) # July 25, 2022 ## New Features * Webhooks are sent for [cip tag status events](/api-references/webhooks/events#cip-tag-status-events) ## Updated Features * Added `user_relationship` field to [receive user object](/api-references/user/add-a-receive-user) # May 23, 2022 ## New Features * New [business payment services](broken://pages/DAW945hokisNvmKTi4pV) * API to [add and update business representative](/api-references/user/business-representatives) ## Updated Features * Added`purpose` (mandatory) and `custom_purpose` fields in [Create Transaction API](/api-references/transaction/create-1) * Added `virtual_documents` and `business` fields in [Get Receive User API](/api-references/user/get-receive-user-list) response * Added `Funding_source_name` to [Get user funding account API ](/api-references/funds/get-user-funding-account)response * Added `physical_document` field in the [Transaction object](/api-references/transaction/create-1) * Added `user_id` in [Add Receive Account API](/api-references/funds/add-a-receive-account) response for payout\_method: BANK\_DEPOSIT * Added business user tier/tags related information in [spec sheet API ](/api-references/data-population/spec-sheet) * Added `txn_supported_types` in the [Get Banks API](/api-references/payout/get-banks) response to outline the transaction types which can be delivered to the specific bank * Added new [transaction hold reasons](/api-references/transaction/create-1) * Updated `account_type` while adding receive accounts # April 7, 2022 ## Updated Features * Changed document\_id field to id\_doc in [Spec Sheet API ](/api-references/data-population/spec-sheet)and [Get Verification status API ](/api-references/user/get-verification-status) # March 30, 2022 ## Updated Features * Changes to [user and document objects](/api-references/user/registration-1) to distinguish between virtual and physical documents. Virtual\_document refers to document information and physical\_documents refer to the copy of the document. This change has affected all APIs related to the user and document object. # March 23, 2022 ## New Features * Current settlement rates will be provided through a [new API](/api-references/data-population/settlement-rates). Transactions will be settled at these rates, although you can set the exchange rates to the user during transaction creation. # Feb 21, 2022 Review this log for all the changes in our APIs and docs. ## New Features * [API to get your spec sheet details](/api-references/data-population/spec-sheet) * [API to get details on KYC information submitted by a user and its verification status](/api-references/user/get-verification-status) * [API to get the remaining transaction limits of a user](/api-references/transaction/get-transaction-limits) ## Updated Features * Removed "tier" field from the response of [Get user by ID](/api-references/user/view) # Feb 15, 2022 Review this log for all the changes in our APIs and docs. ## Updated Features * Updated response for [API to get country details](/api-references/data-population/country#get-countries) enabled for you * "funding\_source\_type" is a mandatory field in [Create transaction API ](/api-references/transaction/create-1) * Added new webhook for [user\_bank\_verification\_failed](/api-references/webhooks/events) funding account event * Added [enumerated values](/api-references/user/registration-1) for document type field in user object * Added mandatory [ID issuing authority](/api-references/user/registration-1) field in user object # Jan 24, 2022 Review this log for all the changes in our APIs and docs. ## New Features * User is able to [add bank](/api-references/funds/funding-account-widget) and create an [ACH transaction](/api-references/transaction/create-1) * New API to [delete send user's funding account](/api-references/funds/delete-user-funding-account). User is also able to delete funding account using the widget. * Webhooks for changes in [delivery status and status of funding accounts](/api-references/webhooks/events) --- [Next Page](/llms-full.txt/1)