Pay By Link
Customers can use PBL(Pay By Link) API to create a payment link which can be sent to the customer to
complete the payment using Velocity POP. This API also supports generation of the payment link in bulk. In
case of bulk operation, every payment link is differentiated by its unique order reference.
When a customer opens the Payment Link it will direct them to a hosted payment page for them to complete their payment.
API Response contains payment links with expiration configured in the request body of the API. Every
payment link is mapped to its request using order_reference present in both request and response.
API Path
| Path Name | Path Details |
|---|---|
| Endpoint | [VELOCITY URL]/cpl/external/create-payment-link |
| Request Method | POST |
| Format/Content Type | text/xml |
| Authentication | HTTP basic access authentication |
API Headers
| Header | Description | Sample Value |
|---|---|---|
| Content-Type | The media type of the resource | application/json |
| x-cpm-auth-token | CPM Security Token is a way for avoiding Man in the Middle attacks in the request and response send from external sources | For generating the token we need: _The request and/or response without white space and in a single line _The base 64 of username and password _The SHA-256 of request + result of base 64 of username and password _The generated token is then passed in the header of the API as x-cpm-sec-token |
| Authorization | Authenticates a user agent with a server, allowing access to a protected resource. This API supports basic Authorization. | Basic YXZpYW5jYTpOZXNOaW5n |
Request
| Field | Type | Required | Description |
|---|---|---|---|
| client_id | Integer | Yes | Merchant identifier number in CPD echo system. |
| account_id | Integer | Yes | Storefront identifier number for merchant in CPD echo system. |
| user_id | Integer | No | User identifier number of who configured payment link. |
| payment_link_source | Integer | Yes | Type identifier for payment link. Value should be =2. |
| amount | JSON | Yes | Shared object type: Reference Link. |
| order_summary | JSON | Yes | Shared object type: Reference Link. |
| customer_info | JSON | No | Shared object type: Reference Link. |
| link_expiry | JSON | Yes | New Object. |
| expiry_type_id | Integer | Yes | Unique identifier for time unit [1=minutes, 2=hours, 3=days] |
| period | Integer | Yes | Time until expiration. (In units above) |
Example Request
{
"payment_links": [
{
"account_id": 20004,
"amount": {
"country_id": 840,
"currency_id": 840,
"decimal": 2,
"value": 266071
},
"client_id": 20004,
"link_expiry": {
"expiry_type_id": 1,
"period": 2
},
"order_summary": {
"order_data": {
"order": {
"line_items": {
"line_item": [
{
"additional_data": {
"param": [
{
"name": "flight_sel_url",
"text": "https://uat.digital.airline.amadeus.com/av/booking/trip?cartId=1PA0O3Y1W517S4CT&pointO\r\n fSale=CO&language=EN&platform=WEBB2C&_ga=2.5637299.1864858949.1697783748-\r\n 192756761.1697783748"
},
{
"name": "info_cust_url",
"text": "https://uat.digital.airline.amadeus.com/av/booking/travelers?lastName=Khan&orderId=3G7\r\n MKE&language=EN&pointOfSale=CO&services=servicesKey&platform=WEBB2C&_ga=2.5637299.18648\r\n 58949.1697783748-192756761.1697783748"
}
]
},
"amount": "131111000",
"fare_summary": {
"base_fare": 93320000,
"currency": "COP",
"service_charges": 10080000,
"taxes_fees": 27711000
},
"product": {
"additional_data": {
"param": [
{
"name": "change_es",
"text": "dW5kZWZpbmVk"
},
{
"name": "refund_es",
"text": "dW5kZWZpbmVk"
},
{
"name": "maximumStay_es",
"text": "dW5kZWZpbmVk"
},
{
"name": "advancePurchase_es",
"text": "dW5kZWZpbmVk"
}
]
},
"airline_data": {
"billing_summary": {
"add_ons": {
"add_on": [
{
"amount": "5040000",
"currency": "COP",
"description": "service.BBAG",
"product_category": "SERVICE",
"product_code": "BBAG",
"product_item": "2ND CHECKED BAG 23KG",
"profile_seq": "1",
"trip_seq": "0",
"trip_tag": "1"
},
{
"amount": "960000",
"currency": "COP",
"description": "service.BBAG_TAX",
"product_category": "TAX",
"product_code": "BBAG",
"product_item": "2ND CHECKED BAG 23KG",
"profile_seq": "1",
"trip_seq": "0",
"trip_tag": "1"
},
{
"amount": "5040000",
"currency": "COP",
"description": "service.BBAG",
"product_category": "SERVICE",
"product_code": "BBAG",
"product_item": "2ND CHECKED BAG 23KG",
"profile_seq": "1",
"trip_seq": "0",
"trip_tag": "2"
},
{
"amount": "960000",
"currency": "COP",
"description": "service.BBAG_TAX",
"product_category": "TAX",
"product_code": "BBAG",
"product_item": "2ND CHECKED BAG 23KG",
"profile_seq": "1",
"trip_seq": "0",
"trip_tag": "2"
}
]
},
"fare_detail": {
"fare": [
{
"amount": "55880000",
"currency": "COP",
"description": "basefare",
"product_category": "FARE",
"product_code": "BASE",
"product_item": "Base Fare",
"profile_seq": "1"
},
{
"amount": "4030000",
"currency": "COP",
"description": "COAE",
"product_category": "TAX",
"product_code": "COAE",
"product_item": "Int. airport facility charge (Colombia) (COAE)",
"profile_seq": "1"
},
{
"amount": "10617000",
"currency": "COP",
"description": "YSTR",
"product_category": "TAX",
"product_code": "YSTR",
"product_item": "Sales tax (Colombia) (YSTR)",
"profile_seq": "1"
},
{
"amount": "37440000",
"currency": "COP",
"description": "basefare",
"product_category": "FARE",
"product_code": "BASE",
"product_item": "Base Fare",
"profile_seq": "2"
},
{
"amount": "4030000",
"currency": "COP",
"description": "COAE",
"product_category": "TAX",
"product_code": "COAE",
"product_item": "Int. airport facility charge (Colombia) (COAE)",
"profile_seq": "2"
},
{
"amount": "7114000",
"currency": "COP",
"description": "YSTR",
"product_category": "TAX",
"product_code": "YSTR",
"product_item": "Sales tax (Colombia) (YSTR)",
"profile_seq": "2"
},
{
"amount": "0",
"currency": "COP",
"description": "basefare",
"product_category": "FARE",
"product_code": "BASE",
"product_item": "Base Fare",
"profile_seq": "3"
},
{
"amount": "0",
"currency": "COP",
"description": "taxDescriptionQ",
"product_category": "FARE",
"product_code": "BASE",
"product_item": "Fuel surcharge (Q)",
"profile_seq": "3"
}
]
}
},
"profiles": {
"profile": [
{
"contact_info": {
"email": "[email protected]",
"mobile": {
"country_id": "405",
"text": "9999999999"
}
},
"first_name": "Gulnawaz",
"last_name": "Khan",
"seq": "1",
"type": "ADT"
},
{
"first_name": "Mahira",
"last_name": "Khan",
"seq": "2",
"type": "CHD"
},
{
"first_name": "Mehwish",
"last_name": "Khan",
"seq": "3",
"type": "INF"
}
]
},
"trips": {
"trip": [
{
"additional_data": {
"param": [
{
"name": "fare_basis",
"text": "SESB3BR9"
}
]
},
"arrival_time": "2023-10-27T06:17:00",
"booking_class": "S",
"departure_time": "2023-10-27T05:14:00",
"destination": {
"country_id": "405",
"external_id": "MDE",
"text": "MDE",
"time_zone": "-5:00"
},
"origin": {
"country_id": "405",
"external_id": "BOG",
"terminal": "1",
"text": "BOG",
"time_zone": "-5:00"
},
"seq": "1",
"service_level": "L",
"tag": "1",
"transportation": {
"carriers": {
"carrier": [
{
"code": "AV",
"number": "9252",
"type": "AIRBUS A320"
}
]
},
"code": "AV",
"number": "9252"
}
},
{
"additional_data": {
"param": [
{
"name": "fare_basis",
"text": "SESB2BR9"
}
]
},
"arrival_time": "2023-11-03T06:45:00",
"booking_class": "S",
"departure_time": "2023-11-03T05:47:00",
"destination": {
"country_id": "405",
"external_id": "BOG",
"terminal": "1",
"text": "BOG",
"time_zone": "-5:00"
},
"origin": {
"country_id": "405",
"external_id": "MDE",
"text": "MDE",
"time_zone": "-5:00"
},
"seq": "1",
"service_level": "M",
"tag": "2",
"transportation": {
"carriers": {
"carrier": [
{
"code": "AV",
"number": "8435",
"type": "AIRBUS A320"
}
]
},
"code": "AV",
"number": "8435"
}
}
]
}
},
"name": "RETURN",
"sku": "3G7MKE"
}
}
]
}
}
},
"reference": "OrderRef8679676546546"
},
"payment_link_source": 2
}
]
}
Response
| Field | Type | Description | Example Value |
|---|---|---|---|
| payment_link | JSON | New Object. | |
| expiry | String | Payment link expiration date/time in UTC. | yyyy-MM-dd HH:mm:ssZ |
| id | Integer | Unique identifier indicating if payment link successfully generated. | Integer value starting from 1 |
| link | String | Actual payment link generated which can be sent to customer to complete payment. | [VELOCITY URL]/cpl/validate-payment-link?secretHash=MTAxMDEyOTQ0MzIxMTcwNjg2MzcwMDMzMw |
| order_summary | JSON | ||
| reference | String | Matches order_reference from request body | LAXPNY1 |
| status | JSON | ||
| code | Integer | Indicates if payment link successfully generated. This is the CPD internal status code. Response HTTP status codes are mentioned along with response samples. | 200=Success 1001=Failed |
| message | String | Indicates if payment link successfully generated. | Payment Link Configured Successfully Failed to Configure Payment Link |
Example Response - Success
{
"payment_links": {
"payment_link": [
{
"expiry": "2023-12-01 00:00:000Z",
"id": 1,
"link": " [VELOCITY URL]/cpl/validate-payment-\r\nlink?secretHash=MTAxMDEyOTQ0MzIxMTcwNjg2MzcwKLyuGF",
"order_summary": {
"reference": "OrderRef1"
},
"status": {
"code": 200,
"message": "Payment Link Configured Successfully"
}
},
{
"expiry": "2023-12-01 00:00:000Z",
"id": 2,
"link": " [VELOCITY URL]/cpl/validate-payment-\r\nlink?secretHash=MTAxMDEyOTQ0MzIxMTcwNjg2MzcwKLopQ",
"order_summary": {
"reference": "OrderRef2"
},
"status": {
"code": 200,
"message": "Payment Link Configured Successfully"
}
}
]
}
}
Example Response - Partial Success
{
"payment_links": {
"payment_link": [
{
"expiry": "2023-12-01 00:00:000Z",
"id": 1,
"link": " [VELOCITY URL]/cpl/validate-payment-\r\nlink?secretHash=MTAxMDEyOTQ0MzIxMTcwNjg2MzcwAhjkl",
"order_summary": {
"reference": "OrderRef1"
},
"status": {
"code": 200,
"message": "Payment Link Configured Successfully"
}
},
{
"order_summary": {
"reference": "OrderRef2"
},
"status": {
"code": 1001,
"message": "Failed to Configure Payment Link"
}
}
]
}
}
Example Response - Invalid Request
{
"payment_links": {
"status": {
"code": 1201,
"message": "Bad Request. Invalid request data."
}
}
}
Example Response - Too many requests.
{
"payment_links": {
"status": {
"code": 1200,
"message": "Bad Request. Request should not contain more than 20 payment links."
}
}
}
Updated 3 months ago