From 1a69f389ef4640093c15b8def720a1b9724a4875 Mon Sep 17 00:00:00 2001 From: dwioy Date: Thu, 4 Apr 2024 12:49:59 +0700 Subject: [PATCH] Feature: Adjust API Docs for Fund Disbursement --- source/includes/_fund_disbursement.md | 206 +++++++++++++++----------- 1 file changed, 121 insertions(+), 85 deletions(-) diff --git a/source/includes/_fund_disbursement.md b/source/includes/_fund_disbursement.md index 2a4521f4..2bd1e16a 100644 --- a/source/includes/_fund_disbursement.md +++ b/source/includes/_fund_disbursement.md @@ -17,7 +17,10 @@ POST https://partner.oyindonesia.com/api/remit \ "amount":125000, "note":"Split lunch bill", "partner_trx_id":"1234-asdf", - "email" :"napoleon@email.com test@email.com" + "email" :"napoleon@email.com test@email.com", + "additional_data": { + "partner_merchant_id": "merchant_abcd123" + } }' ``` @@ -229,61 +232,63 @@ Use this API to start disbursing money to a specific beneficiary account. | Parameter | Type | Required | Description | |-------------------|-------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| recipient_bank | String(255) | TRUE | Bank Code of the Beneficiary account, see [Disbursement Bank Codes](#disbursement-bank-codes-) | -| recipient_account | String(255) | TRUE | Beneficiary account number, numeric only | -| amount | BigInteger | TRUE | Amount of disbursement (Accept Non-Decimal Number), min amount 10000 | -| note | String(255) | FALSE | Add Note to the transaction | -| partner_trx_id | String(255) | TRUE | Unique disbursement ID for a specific request, generated by partner | -| email | String(255) | FALSE | Email for invoice notification (Optional). Email can be more than one but not more that five separated by a whitespace. | -| child_balance | String(255) | FALSE | Child username whom balance will be used for disbursement, if [Multi Account Management](https://docs.oyindonesia.com/#multi-account-management-oy-dashboard-tutorial) config is active (Optional). By default will be using client’s own balance. | +| recipient_bank | String(255) | TRUE | Please refer to the [Disbursement Bank Codes](#disbursement-bank-codes-) to find the bank code for the recipient's bank account. | +| recipient_account | String(255) | TRUE | Recipient bank account number, numeric only. | +| amount | BigInteger | TRUE | Amount of disbursement, the minimum amount for bank is Rp10.000 and e-wallet is Rp100. | +| note | String(255) | FALSE | The transaction's message may or may not be reflected in the recipient's bank account statement, based on the bank's capabilities. Using alphanumeric characters and some common symbols (e.g. -, *, . ) | +| partner_trx_id | String(255) | TRUE | Unique disbursement ID for a specific request, generated by partner. | +| email | String(255) | FALSE | Multiple emails allowed, max. 5, separated by space. E.g. john.doe@example.com budi@example.com stark@example.com | +| child_balance | String(255) | FALSE | If the [Multi Account Management](https://docs.oyindonesia.com/#multi-account-management-oy-dashboard-tutorial) configuration is active, the disbursement will use the balance of child (sub-entity) account. Otherwise, the partner's own balance will be used by default. | +| additonal_data | Object | FALSE | Object that includes the additional parameter for partner’s needs. This object contain `partner_merchant_id String(64) (Unique ID for each of partner’s merchant)` | ### Response Parameters | Parameter | Type | Description | |-------------------|-------------|------------------------------------------------------------------------------------------------| | status | Object | Status of Disbursement in Object `{code: , message: }` | -| amount | BigInteger | Amount of disbursement (Accept Non-Decimal Number) | -| recipient_bank | String(255) | Bank Code of the Beneficiary account, see [Disbursement Bank Codes](#disbursement-bank-codes-) | -| recipient_account | String(255) | Beneficiary account number | -| trx_id | String(36) | Unique Disbursement ID from OY!. Partner can use this ID for settlement | -| partner_trx_id | String(255) | Unique Disbursement ID which partner put on the Request | -| timestamp | String(19) | Execution time of Disbursement in OY! system ("dd-MM-yyyy HH:mm:ss in UTC Time zone") | - -### Transaction Status: API Create Disbursement - -Below is the list of response codes that show the transaction status for API Create Disbursement: - -| Response Code | State | Description | -|---------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 000 | Final | Transaction has been completed (success). Note: only happens for overbooking flow. | -| 101 | Non-Final | Transaction is Processed | -| 102 | Non-Final | Transaction is In Progress | -| 206 | Final | Transaction is FAILED (Partner Deposit Balance is Not Enough) | -| 225 | Final | Transaction is FAILED (Transaction amount exceeds the maximum limit) | -| 300 | Final | Transaction is FAILED | -| 301 | Non-Final | Pending (When there is an unclear answer from Banks Network) | -| 504 | Non-Final | Remit Submission Timed Out. Note: the transaction status is uncertain - it may or may not have been successfully submitted, so we suggest resubmitting using the same partner_trx_id | +| amount | BigInteger | Amount to disburse. | +| recipient_bank | String(255) | Bank or Ewallet code of the recipient’s account, please refer to [Disbursement Bank Codes](#disbursement-bank-codes-) | +| recipient_account | String(255) | Recipient bank account number. | +| trx_id | String(36) | Unique disbursement ID from OY!, partners can use this ID for reconciliation. | +| partner_trx_id | String(255) | Unique disbursement ID which partner put on the request. | +| timestamp | String(19) | Creation time of disbursement transaction in OY! system, using the format "dd-mm-yyyy hh:mm:ss" in UTC time. | - -### Request Status: API Create Disbursement +### Response Code: API Create Disbursement Below is the list of response codes that show the request status for API Create Disbursement: -| Response Code | State | Description | Notes | +| Response Code | State | State Details | Description | |---------------|-----------|------------------------------------------------------------------------------------|----------------------------------------------------| -| 203 | Final | Request is Rejected (Duplicate Partner Tx ID) | Request Rejected. Transaction Not Created | -| 201 | Final | Request is Rejected (User ID is not Found) | Request Rejected. Transaction Not Created | -| 202 | Final | Request is Rejected (User ID is not Active) | Request Rejected. Transaction Not Created | -| 205 | Final | Request is Rejected (Beneficiary Bank Code is Not Supported) | Request Rejected. Transaction Not Created | -| 207 | Final | Request is Rejected (Request IP Address is not Registered) | Request Rejected. Transaction Not Created | -| 208 | Final | Request is Rejected (API Key is not Valid) | Request Rejected. Transaction Not Created | -| 209 | Final | Request is Rejected (Bank Account is not found) | Request Rejected. Transaction Not Created | -| 210 | Final | Request is Rejected (Amount is not valid) | Request Rejected. Transaction Not Created | -| 257 | Final | Request is Rejected (Disbursement with the same Partner Tx ID is still in process) | Request Rejected. Transaction Not Created | -| 429 | Final | Request Rejected (Too Many Request to specific endpoint) | Request Rejected. Transaction Not Created | -| 990 | Final | Request is Rejected (Invalid Format) | Request Rejected. Transaction Not Created | -| 999 | Non-Final | Internal Server Error | Unclear answer from OY system, please check status | - +| 101 | Non-Final | Transaction In Progress | Transaction is processed. | +| 201 | Final | Transaction Not Created | Request is Rejected (User ID is not Found) | +| 202 | Final | Transaction Not Created | Request is Rejected (User ID is not Active) | +| 203 | Final | Transaction Not Created | Request is Rejected (Duplicate Partner Tx ID) | +| 205 | Final | Transaction Not Created | Request is Rejected (Beneficiary Bank Code is Not Supported) | +| 207 | Final | Transaction Not Created | Request is Rejected (Request IP Address is not Registered) | +| 208 | Final | Transaction Not Created | Request is Rejected (API Key is not Valid) | +| 209 | Final | Transaction Not Created | Request is Rejected (Bank Account is not found) | +| 210 | Final | Transaction Not Created | Request is Rejected (Amount is not valid) | +| 257 | Final | Transaction Not Created | Request is Rejected (Disbursement with the same Partner Tx ID is still in process) | +| 264 | Final | Transaction Not Created | Request is rejected (The suggested routing from the partner is not valid) | +| 300 | Final | Transaction Failed | Transaction is failed. | +| 301 | Non-Final | Transaction Pending | Pending (when there is an unclear answer from bank network) | +| 429 | Final | Transaction Not Created | Request Rejected (Too Many Request to specific endpoint) | +| 504 | Non-Final | Transaction Unknown | Disbursement Submission Timed Out. Note: the transaction status is uncertain, it may or may not have been successfully submitted, so we suggest resubmitting using the same partner_trx_id. Please check your dashboard or contact our business representative. | +| 990 | Final | Transaction Not Created | Request is Rejected (Invalid Format) | +| 999 | Non-Final | Transaction Unknown | Internal Server Error. Please check your dashboard or contact our business representative | + + +### Column State Details: Response Code API Create Disbursement + +Below is the list of Explanation for column state details that show on response code API Create Disbursement: + +| State Details | Description | +|---------------| ---------------------------------------------------- | +| Transaction Failed | Transaction is failed to disburse. | +| Transaction In Progress | Transaction is still in progress. | +| Transaction Pending | Transaction has an unclear status from the banks. | +| Transaction Unknown | Transaction status is uncertain, please wait the callback or hit check status API to make sure the status of transaction. Please check to your dashboard or contact our business representative. | +| Transaction Not Created | Transaction is not created in the OY! system due to not valid disbursement request. | **[Staging only]** @@ -329,15 +334,15 @@ We also have a resend callback feature which you can read about [here](https://d Parameter | Type | Description --------- | ---- | ----------- status | Object | Status of Disbursement in Object `{code: , message: }` -tx_status_description | String(255) | additional information of status code (e.g. FORCE CREDIT) -amount | BigInteger | Amount of disbursement (Accept Non-Decimal Number) -recipient_name | String(255) | Account holder name of Beneficiary account number -recipient_bank | String(255) | Bank Code of the Beneficiary account, see [Disbursement Bank Codes](#disbursement-bank-codes-) -recipient_account | String(255) | Beneficiary account number -trx_id | String(36) | Unique Disbursement ID from OY!. Partner can use this ID for settlement -partner_trx_id | String(255) | Unique Disbursement ID which partner put on the Request, generated by partner -timestamp | String(19) | Execution time of API remit status in OY! system ("dd-MM-yyyy HH:mm:ss" in UTC Time zone) -created_date | String(19) | Executionn time of Disbures in OY! system ("dd-MM-yyyy HH:mm:ss" in UTC Time zone) +tx_status_description | String(255) | Additional information of status code, especially for failed status e.g. “Account is blocked. Please create a new transaction with a different recipient account number.” +amount | BigInteger | Amount to disburse. +recipient_name | String(255) | Account holder name of recipient bank account. +recipient_bank | String(255) | Bank or Ewallet code of the recipient’s account, please refer to [Disbursement Bank Codes](#disbursement-bank-codes-) +recipient_account | String(255) | Recipient bank account number. +trx_id | String(36) | Unique disbursement ID from OY!, partners can use this ID for reconciliation. +partner_trx_id | String(255) | Unique disbursement ID which partner put on the request. +timestamp | String(19) | Time of API get disbursement status called by partner ("dd-MM-yyyy HH:mm:ss in UTC time zone"). +created_date | String(19) | Execution time of disbursement in OY! system ("dd-MM-yyyy HH:mm:ss in UTC time zone"). last_updated_date | String(19) | Latest status change of a disbursement. Example from 'Pending' to 'Success' ("dd-MM-yyyy HH:mm:ss in UTC Time zone") ### Transaction Status: API Disbursement @@ -567,42 +572,73 @@ send_callback | Boolean | FALSE | A flag to indiciate if the status of the disbu Parameter | Type | Description --------- | ---- | ----------- status | Object | Status of Disbursement in Object `{code: , message: }` -tx_status_description | String(255) | additional information of status code (e.g. FORCE CREDIT) -amount | BigInteger | Amount of disbursement (Accept Non-Decimal Number) -recipient_name | String(255) | Account holder name of Beneficiary account number -recipient_bank | String(255) | Bank Code of the Beneficiary account, see [Disbursement Bank Codes](#disbursement-bank-codes-) -recipient_account | String(255) | Beneficiary account number -trx_id | String(36) | Unique Disbursement ID from OY!. Partner can use this ID for settlement -partner_trx_id | String(255) | Unique Disbursement ID which partner put on the Request, generated by partner -timestamp | String(19) | Execution time of API remit status in OY! system ("dd-MM-yyyy HH:mm:ss in UTC Time zone") -created_date | String(19) | Executionn time of Disbures in OY! system ("dd-MM-yyyy HH:mm:ss in UTC Time zone") +tx_status_description | String(255) | Additional information of status code, especially for failed status. E.g. Account is blocked. Please create a new transaction with a different recipient account number. +amount | BigInteger | Amount to disburse. +recipient_name | String(255) | Account holder name of recipient bank account. +recipient_bank | String(255) | Bank or Ewallet code of the recipient’s account, please refer to [Disbursement Bank Codes](#disbursement-bank-codes-) +recipient_account | String(255) | Recipient bank account number. +trx_id | String(36) | Unique disbursement ID from OY!, partners can use this ID for reconciliation. +partner_trx_id | String(255) | Unique disbursement ID which partner put on the request. +timestamp | String(19) | Time of API get disbursement status called by partner ("dd-MM-yyyy HH:mm:ss in UTC time zone"). +created_date | String(19) | Execution time of disbursement in OY! system ("dd-MM-yyyy HH:mm:ss in UTC time zone"). last_updated_date | String(19) | Latest status change of a disbursement. Example from 'Pending' to 'Success' ("dd-MM-yyyy HH:mm:ss in UTC Time zone") -### Transaction Status: API Get Disbursement Status -Below is the list of response codes that show the transaction status for API Get Disbursement Status: +### Response Code: API Get Disbursement Status -| Response Code | State | Description | -|---------------|-----------|---------------------------------------------------------------| -| 000 | Final | Transaction has been completed (success) | -| 101 | Non-Final | Transaction is Processed | -| 102 | Non-Final | Transaction is In Progress | -| 204 | Final | Transaction do not exist (Partner Tx ID is Not Found) | -| 206 | Final | Transaction is FAILED (Partner Deposit Balance is Not Enough) | -| 300 | Final | Transaction is FAILED | -| 301 | Non-Final | Pending (When there is an unclear answer from Banks Network) | - -### Request Status: API Get Disbursement Status Below is the list of response codes that show the request status for API Get Disbursement Status: -| Response Code | State | Description | Notes | -|---------------|-----------|------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------| -| 201 | Non-Final | Request is Rejected (User ID is not Found) | Request check status rejected. Doesn't represent transaction status. This response usually appears during the integration process. | -| 202 | Non-Final | Request is Rejected (User ID is not Active) | Request check status rejected. Doesn't represent transaction status. This response usually appears during the integration process. | -| 207 | Non-Final | Request is Rejected (Request IP Address is not Registered) | Request check status rejected. Doesn't represent transaction status. This response usually appears during the integration process. | -| 208 | Non-Final | Request is Rejected (API Key is not Valid) | Request check status rejected. Doesn't represent transaction status. This response usually appears during the integration process. | -| 429 | Non-Final | Request Rejected (Too Many Request to specific endpoint) | Request check status rejected. Doesn't represent transaction status. | -| 990 | Non-Final | Request is Rejected (Invalid Format) | Request check status rejected. Doesn't represent transaction status. | -| 999 | Non-Final | Internal Server Error | Request check status rejected. Doesn't represent transaction status. | +| Response Code | State | State Details | Description | +|---------------|-----------|------------------------------------------------------------------------------------|----------------------------------------------------| +| 000 | Final | Transaction Success | Transaction has been completed. | +| 101 | Non-Final | Transaction In Progress | Transaction is processed. | +| 102 | Non-Final | Transaction In Progress | Transaction is in progress. | +| 201 | Non-Final | Transaction Unknown | Request for Get Disbursement Status is rejected (user ID is not found) | +| 202 | Non-Final | Transaction Unknown | Request for Get Disbursement Status is rejected (user ID is not active) | +| 204 | Final | Transaction Not Created | Transaction do not exist (Partner Tx ID is Not Found) | +| 206 | Final | Transaction Failed | Transaction is failed (partner deposit balance is not enough) | +| 207 | Non-Final | Transaction Unknown | Request for Get Disbursement Status is rejected (request IP Address is not registered) | +| 208 | Non-Final | Transaction Unknown | Request for Get Disbursement Status is rejected (API key is not valid) | +| 225 | Final | Transaction Failed | Transaction is failed (Transaction amount exceeds the maximum limit) | +| 300 | Final | Transaction Failed | Transaction is failed. | +| 301 | Non-Final | Transaction Pending | Pending (when there is an unclear answer from bank network) | +| 429 | Non-Final | Transaction Unknown | Request for Get Disbursement Status is rejected (too many requests to specific endpoint) | +| 990 | Final | Transaction Unknown | Request for Get Disbursement Status is rejected (invalid format) | +| 999 | Non-Final | Transaction Unknown | Internal Server Error | + + +### Column State Details: Response Code API Get Disbursement Status + +Below is the list of Explanation for column state details that show on response code API Get Disbursement Status: + +| State Details | Description | +|---------------| ---------------------------------------------------- | +| Transaction Success | Transaction has been completed & successfully received on the recipient account | +| Transaction Failed | Transaction is failed to disburse. | +| Transaction In Progress | Transaction is still in progress. | +| Transaction Pending | Transaction has an unclear status from the banks. | +| Transaction Unknown | Transaction status is uncertain, please wait the callback or hit check status API to make sure the status of transaction. Please check to your dashboard or contact our business representative. | +| Transaction Not Created | Transaction is not created in the OY! system due to not valid disbursement request. | | + + +## Disbursement Failed Reasons + +If you receive a failed disbursement in the callback or check status response, this means that we tried processing the disbursement and failed. + +We return failed reasons description in our callback & check status response in the `tx_status_description parameter`. Partners need to understand each failed reason to decide the appropriate action to take. Below is a list of the failed reasons that partners may receive: + +### Explanation: Disbursement Failed Reasons + +Failed Reason | Explanation | Should I retry? +------------- | ----------- | -------------- +Account is blocked. Please create a new transaction with a different recipient account number. | Recipient account number is blocked by the bank & disbursement cannot proceed to this account. | If you retry with the same request, most likely it will return the same response. Please confirm to the recipient that the account number details are correct and can receive funds. After that, you can revise the request to the correct account number before trying again. +Account has exceeded the maximum amount for receiving money. Please contact the account owner. | Recipient account number has reached the balance limit amount that is set by the corresponding bank/e-wallet. | If you retry with the same request, most likely it will return the same response. Please confirm to the recipient that the account number details can receive funds for that amount. After that, you can revise the request to the correct account number and amount before trying again. +Account is no longer active. Please create a new transaction with a different recipient account number. | Recipient account number is no longer active in the bank & disbursement cannot proceed to this account. | If you retry with the same request, most likely it will return the same response. Please confirm to the recipient that the account number details are correct and can receive funds. After that, you can revise the request to the correct account number before trying again. +Account not found. Please create a new transaction with a different recipient account number.| Recipient account number is not found for the bank selected & disbursement cannot proceed to this account. | If you retry with the same request, most likely it will return the same response. Please confirm to the recipient that the account number details and the selected bank are correct and can receive funds. After that, you can revise the request to the correct account number before trying again. +The bank/e-wallet provider system is under maintenance. Please try again in a moment.| The bank/e-wallet is in downtime so there will be disturbances in the disbursement process. | Please ensure the information of the bank maintenance schedule to our customer service. If there is any clear information about the maintenance schedule from the banks, you can retry the transaction after the maintenance schedule is over. +The bank/e-wallet system encounters an error while disbursing the money. Try again in a moment. | The bank/e-wallet has an issue in their system to process the disbursement. There may be intermittent issues in the bank system that are unpredictable. | You can retry the disbursement in the next few minutes. If you need any further information regarding the issue, you can contact our customer service. +System encounters an error while disbursing the money. Please try again in a moment. | There is an issue in the process of the disbursement. There may be intermittent issues that are unpredictable. | You can retry the disbursement in the next few minutes. If you need any further information regarding the issue, you can contact our customer service. +Your transaction exceeds the maximum limit amount. Please adjust the amount and try again. | The transaction has an amount that exceeds the maximum limit that is already set in the OY! system. | If you retry with the same request, it will return the same response. Please adjust the transaction amount according to the maximum limit that OY! gives to you. If you need any further information regarding the limit amount, you can contact our business representative. +Not enough balance to disburse the money, please top up your balance. | Insufficient partner’s deposit balance to process the disbursement transaction. | Please top up your deposit balance in the OY! dashboard. You can retry the disbursement transaction after ensuring that you have sufficient balance in your account. ## Get Balance