# Payment Order Generate
# Specification
- The following table is a specification of this API:
| Name | Description |
|---|---|
| API Name | API Direct Debit Payment |
| Function | This API is used to create Direct Debit Payment from merchant to PayCools as the acquirer |
| Service Code | 54 |
| Method | POST |
| URL | /v2.0/debit/payment-host-to-host |
| Accept | application/json |
| Content Type | application/json |
| Related Service | |
| Expected Timeout | 8 second |
# Request
- The following part will be describe about parameter of request in this API:
# Request Parameter
- The following table is a list of request parameter in this API:
# Header
- The following table is a header of request parameter:
| No | Name | Type | Length | Required | Condition | Remarks |
|---|---|---|---|---|---|---|
| 1 | Content-Type | String | Variable, 127 max | Mandatory | - | Content type, value always application/json |
| 2 | Authorization | String | Variable, 2048 max | Mandatory | Represents access_token of a request, starts with keyword “Bearer” and followed by access_token | |
| 3 | X-TIMESTAMP | String | Fixed, 25 max | Mandatory | - | Transaction date time, in format YYYY-MM-DDTHH:mm:ss+07:00. Time must be in GMT+7 (Jakarta time) |
| 4 | X-SIGNATURE | String | Variable | Mandatory | - | created using asymmetric signature SHA256withRSA algorithm of X-CLIENT-KEY + “|” + X-TIMESTAMP for example：3a34d6a9debb4246931f3941c471dd3b|2023-09-25T17:57:35+07:00 |
| 5 | X-PARTNER-ID | String | Variable, 36 max | Mandatory | - | Unique identifier for partner was generated by PayCools, or known as appId |
# Body
- The following table is a body of request parameter:
| No | Name | Type | Length | Required | Condition | Remarks |
|---|---|---|---|---|---|---|
| 1 | partnerReferenceNo | String | Variable, 50 max | Mandatory | - | Unique transaction identifier in client system. |
| 2 | amount | MONEY | Variable, 64 max | Mandatory | - | |
| 3 | merchantId | String | Variable, 64 max | Mandatory | - | Unique identifier for partner was generated by PayCools, or known as appId |
| 4 | additionalInfo | AdditionalInfo | Variable | Mandatory | - | Additional information |
# REQUEST SAMPLE
POST /v2.0/debit/payment-host-to-host HTTP/1.1
Content-type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhcHBJZCI6ImNiY2U0OTBlODJmODQxZjJiMzE2MmE4ZGQyN2U5ZmQxIiwiY2FjaGVLZXkiOiJUT0tFTl9BUElfY2JjZTQ5MGU4MmY4NDFmMmIzMTYyYThkZDI3ZTlmZDFfMjEwMDJiMGYtMDJkNS00ZDI2LTg4MmEtMGRmNWI5MzVlNWVhIiwiY3JlYXRlVGltZSI6MTY5NjY1MDAyMTg3OX0.mkiFEVNvWTJDVLTvY9oE2u4w76wnlra1mwzC79SG-Zo
X-TIMESTAMP: 2023-09-25T17:57:35+07:00
X-SIGNATURE:
Dupbr1ILxsfBrXFmeDdIjwCmgv6AF+JQeIpD1Gq8HDjow7avCXdZAPOEbxVe7/x0atxy86aUfC11zXA1gvXXwxrTXFr6V0x8GZCyTndqnDyRlBeEZLL3BLmDRkrSsomd/mv1eG/th4TQndSPrBBfbN3bj0yIB99y2BnU5fBy7B0ZhYiQVs3uREspIsBB99F/4Zv8GbPWvik2usdOUo0gfPAQoZ3MJAcBQ/0vMRT5KdLm903C2HNyl1Cpb6OFRgaU2LAWybEQIC2QJ9mFb08NPR0PEu75WpVHNrFYn8gfiI8nRso0vBJhtMZrRINDQf9scV53cFdjpWobQHvnFDHCqQ==
X-PARTNER-ID: cbce490e82f441f2b3162a2dd27e8fd1
{
"partnerReferenceNo": "test202310457895245",
"amount": {
"value": "30000.00",
"currency": "IDR"
},
"merchantId": "cbce490e82f441f2b3162a2dd27e8fd1",
"additionalInfo": {
"channelCode": "OVO_URL",
"notifyUrl": "https://www.google.com",
"redirectUrl": "https:///www.google.com",
"customerName":"test123",
"customerMobile":"09123456789",
"feeSplitType": 1,
"items": [
{
"regionNo": "12356",
"branchNo": "123456",
"courierNo": "123456",
"subOrderId": "123456",
"amount": {
"value": "30000.00",
"currency": "IDR"
}
}
]
}
}
# Response
- The following part will be describe about parameter of response in this API:
# Response Parameter
- The following table is a list of response parameter in this API:
# Header
- The following table is a header of response parameter:
| No | Name | Type | Length | Required | Condition | Remarks |
|---|---|---|---|---|---|---|
| 1 | Content-Type | String | Variable, 127 max | Mandatory | - | Content type, value always application/json |
| 2 | X-TIMESTAMP | String | Fixed, 25 max | Mandatory | - | Transaction date time, in format YYYY-MM-DDTHH:mm:ss+07:00. Time must be in GMT+7 (Jakarta time) |
# Body
- The following table is a body of response parameter:
| No | Name | Type | Length | Required | Condition | Remarks |
|---|---|---|---|---|---|---|
| 1 | responseCode | String | Fixed, 7 max | Mandatory | - | Refer to response code list |
| 2 | responseMessage | String | Variable, 150 max | Mandatory | - | Refer to response code list |
| 3 | referenceNo | String | Variable | Mandatory | Y:= Successfully processed | Transaction identifier in PayCools system |
| 4 | partnerReferenceNo | String | Variable, 50 max | Mandatory | - | Unique transaction identifier in client system. |
| 5 | webRedirectUrl | String | Variable, 512 max | Conditional | Y:= Successfully processed | |
| 6 | aggregateAmount | MONEY | Variable | Conditional | Y:= Successfully processed | Aggregate Amount |
| 7 | aggregateFeeAmount | MONEY | Variable | Conditional | Y:= Successfully processed | Aggregate Fee Amount |
| 8 | totalAggregateAmount | MONEY | Variable | Conditional | Y:= Successfully processed | Total Aggregate Amount |
| 9 | additionalInfo | AdditionalInfoResp | Variable | Mandatory | Y:= Successfully processed | Additional information |
# Response
Content-Type: application/json
X-TIMESTAMP: 2023-04-11T21:10:11+07:00
{
"responseCode": "2005400",
"responseMessage": "Successful",
"webRedirectUrl": "https://www.example.com/webpay/ovo/xpYDQOukR39Fp4ktv16tNw==",
"aggregateAmount": {
"value": "30000.00",
"currency": "IDR"
},
"aggregateFeeAmount": {
"value": "2000.00",
"currency": "IDR"
},
"totalAggregateAmount": {
"value": "30000.00",
"currency": "IDR"
},
"additionalInfo": {
"channelCode": "OVO_URL",
"notifyUrl": "https://www.google.com",
"redirectUrl": "https://www.google.com",
"customerName": "test123",
"email": null,
"customerMobile": "09123456789",
"remark": null,
"feeSplitType": 1,
"items": [
{
"regionNo": "12356",
"branchNo": "123456",
"courierNo": "123456",
"courierName": null,
"courierMobile": null,
"subOrderId": "123456",
"amount": {
"value": "30000.00",
"currency": "IDR"
},
"feeAmount": {
"value": "2000.00",
"currency": "IDR"
},
"totalAmount": {
"value": "30000.00",
"currency": "IDR"
}
}
]
}
}
# Response Code and Message
- The following table is the list response code and message of Balance Inquiry API:
| No | Response Code | Response Message | Remarks | Partner Action | Related Service |
|---|---|---|---|---|---|
| 1 | 2005400 | Successful | Success to be processed | Mark Direct Debit Payment process as Success | Direct Debit Payment - SNAP |
| 3 | 4005400 | Bad Request | General request failed error | Mark Direct Debit Payment process as Failed. Retry request with proper parameter | Direct Debit Payment - SNAP |
| 4 | 4005401 | Invalid Field Format | Invalid format for certain field | Mark Direct Debit Payment process as Failed. Retry request with proper parameter | Direct Debit Payment - SNAP |
| 5 | 4005402 | Invalid Mandatory Field | Missing or invalid format on mandatory field | Mark Direct Debit Payment process as Failed. Retry request with proper parameter | Direct Debit Payment - SNAP |
| 6 | 4015400 | Unauthorized. [reason] | General unauthorized error | Mark Direct Debit Payment process as Failed. Retry request with proper parameter | Direct Debit Payment - SNAP |
| 7 | 4015401 | Invalid Token (B2B) | Authorization token are invalid, perhaps due to token expiry for B2B | Mark Direct Debit Payment process as Failed. Retry request with proper parameter | Direct Debit Payment - SNAP |
| 8 | 4035402 | Exceeds Transaction Amount Limit | Exceeds transaction amount limit | Mark Direct Debit Payment process as Failed. Try to adjust the order amount | Direct Debit Payment - SNAP |
| 9 | 4035405 | Do Not Honor | Account or user status is abnormal | Mark Direct Debit Payment process as Failed. Retry request with proper parameter or can contact PayCools to check the user/account status | Direct Debit Payment - SNAP |
| 10 | 4035415 | Transaction Not Permitted.[reason] | Transaction not permitted | Mark Direct Debit Payment process as Failed. Retry request periodically or consult to PayCools | Direct Debit Payment - SNAP |
| 11 | 4045408 | Invalid Merchant | Merchant does not exist or status abnormal | Mark Direct Debit Payment process as Failed. Retry request with proper parameter | Direct Debit Payment - SNAP |
| 12 | 4045418 | Inconsistent Request | Inconsistent request parameter found for the same partner reference number/transaction identifier | Mark Direct Debit Payment process as Failed. Retry request with proper parameter | Direct Debit Payment - SNAP |
| 13 | 4295400 | Too Many Requests | Maximum transaction limit exceeded | Mark Direct Debit Payment process as Failed. Retry request with proper parameter | Direct Debit Payment - SNAP |
| 14 | 5005400 | General Error | General error non retry-able | Mark Direct Debit Payment process as Failed. Retry request periodically | Direct Debit Payment - SNAP |
| 15 | 5005401 | Internal Server Error | Unknown internal server failure, please retry the process again | Mark Direct Debit Payment process as Failed. Retry request periodically | Direct Debit Payment - SNAP |
| 16 | Total Timeout | Total timeout, the client side does not get any responses from the server side (can be due to network issue, server slowing down, and so on) | Do a retry maximum 3 attempts, if the result is still the same then action is aborted. Show appropriate error message to users | Direct Debit Payment - SNAP | |
| 17 | Unexpected response (empty field/field does not exist/undefined response code) | The server does not produce expected responses (can be due to hardware failure, bugs, and so on) | Do a retry maximum 3 attempts, if the result is still the same then action is aborted. Show appropriate error message to users | Direct Debit Payment - SNAP |