PayU Pay-by-Link
- Initiate Authorization
- Collect Payment Option Details via SDK
- Transmission of Payment Details
- Customer Is Redirected to Their Bank's Login Webpage
- Customer Confirms Transaction
- Bank Authorizes Transaction
- Complete Authorization
- PaymentsOS Callback
1. Initiate Authorization
The "PayU Pay-by-Link", "PayU Installments", "TWISTO Pay Later" and "BLIK" payment options are offered via the PaymentsOS external payment provider.
The process of initiating a Guest Payment using either one is nearly identical, with only the difference of providing the corresponding payment option code.
For this reason the following example is provided only for "PayU Pay-by-Link".
The authorization of a payment is initialized by calling the API method 1.38 Init Authorize.
In the example below, we authorize 3.99 EUR for a PayU "Pay-by-Link" payment as part of the purchase of two premium widgets from Widgets GmbH. The shopper's full name is provided alongside their address.
The new PaymentsOS integration version 1.3.0 requires to specify the custom header "X-Ip-Address" in the API method 1.38 Init Authorize.
Initiate Authorization Request
Path:
PUT {baseURL}/payment/initAuthorize
Header:
Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=
X-Ip-Address: 123.123.123.123
{
"partnerReference": "DEV-SVR001-DE_CUSTID-MR64T3GYMY_CARTID-TGXTM3BHRF_W3C6FCBDWB",
"programAccno": "1714963780",
"accno": "1715009450",
"accnoType": "01",
"paymentOptionCode": "PAYU",
"presentationAmount": 3.99,
"presentationCurrCode": "PLN",
"presentationUsage": "Purchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95. Hotline:08001234567.",
"useDifferentBillingAddress": true,
"customerFullName": "Jacob Smith",
"addr1": "Anystreet",
"houseNumber": "321",
"city": "Anycity",
"countryCode": "DE",
"postCode": "12345",
"criteria": [
{
"name": "redirectUrl",
"value": "https://example.com/Checkout/CompleteOrder"
}
],
"localDate": "2019-04-11",
"localTime": "184834"
}
Only URLs starting with "https://" are permitted as the value of "redirectUrl"
It is strongly advised that real customer information be accurately provided - i.e., "useDifferentBillingAddress" being set to true, making the below mandatory:
- customerFullName
- addr1
- houseNumber (if not included in "addr1")
- city
- postCode
- countryCode
It is advised that "emailAddress" also be provided, with accurate customer data.
Please discuss with you business contacts when providing accurate data may not be possible in production, as it may result in transactions being rejected.
If the value of "countryCode" is "US" (United States of America) or "CA" (Canada) the "state" parameter is required. The value of "state" must be a valid State Code. (ex. "countryCode": "US", "state": "NY",)
The maximum character length of the presentation usage (see variable presentationUsage in the example above) varies between payment options. It may be that with certain payment options the specified presentation usage may be less than 127 and consequently be truncated. It would thus be strongly recommended that the most pertinent information be placed at the beginning of the presentation usage. To be compatible with most payment options we suggest that the presentation usage already be truncated at the 22nd character.
Initiate Authorization Response
Status Code:
201 (Created)
Header:
Content-Type: application/json
Accept-Language: en-US
{
"programAccno": "1714963780",
"accno": "1715009450",
"uniqueReference": "T9KGCM5AN0y-l9eowgV82Q",
"loadAccountReference": "NvPoE85cZE6FguOfrC7Fmw",
"authorizationToken": "https://merch-prod.snd.payu.com/pay/?orderId=TFM{partial omission for brevity}jRFJGp0",
"paymentOptionCode": "PAYU",
"presentationAmount": 3.99,
"presentationCurrCode": "PLN",
"presentationUsage": "Purchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95. Hotline:08001234567.",
"custom1": "WVWZZZ3BZWE689725",
"statusCode": "RECEIVED",
"statusReason": "Pending",
"paymentProviderResponse": [
{
"id": "8a4c674e-b05c-4465-98b2-f71027fb5147",
"currency": "PLN",
"created": "1555001316327",
"modified": "1555001316327",
"amount": 3.99,
"order": {
"id": "Umbrella Europe T9KGCM5AN0y-l9eowgV82Q",
"line_items": [
{
"name": "Purchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95. Hotline:08001234567.",
"id": "Umbrella Europe",
"quantity": 1,
"unit_price": 3.99
}
]
},
"status": "Initialized",
"billing_address": {},
"possible_next_actions": [
{
"action": "Charge",
"href": "https://api.paymentsos.com/payments/8a4c674e-b05c-4465-98b2-f71027fb5147/charges"
},
{
"action": "Authorization",
"href": "https://api.paymentsos.com/payments/8a4c674e-b05c-4465-98b2-f71027fb5147/authorizations"
},
{
"action": "Update Payment",
"href": "https://api.paymentsos.com/payments/8a4c674e-b05c-4465-98b2-f71027fb5147"
}
]
},
{
"id": "806e11a7-ba1b-41f8-be93-4c5e7f36e013",
"amount": 3.99,
"created": "1555001316877",
"reconciliation_id": "T9KGCM5AN0y-l9eowgV82Q",
"provider_specific_data": {
"additional_details": {
"bank_name": "payment_wall",
"language": "en"
}
},
"payment_method": {
"type": "PBL"
},
"ip_address": "123.123.123.123",
"originating_purchase_country": "LUX",
"result": {
"status": "Pending"
},
"provider_data": {
"provider_name": "PayUPoland",
"response_code": "SUCCESS",
"raw_response": "{\"redirectUri\":\"{baseUrl}/pay/?orderId=TFM...",
"external_id": "TFMFGQ5PGR190411GUEST000P01"
},
"redirection": {
"id": "b0275d86-890f-495e-a1ce-a6a9290a692f",
"created": "1555001316851",
"merchant_site_url": "https://example.com/Checkout/CompleteOrder?id=T9KGCM5AN0y-l9eowgV82Q",
"url": "{baseUrl}/pay/?orderId=TFM..."
}
}
],
"partnerReference": "DEV-SVR001-DE_CUSTID-MR64T3GYMY_CARTID-TGXTM3BHRF_W3C6FCBDWB",
"localDate": "2019-04-11",
"localTime": "184834",
"sysDate": "2019-04-11",
"sysTime": "164837",
"responseCode": "0000",
"responseDescription": "Successful execution",
"additionalInformation": {
"requestId": "aff2728481a181dc36daedc14055b516"
}
}
The response includes the desired authorization token under the return parameter "authorizationToken" which is used to collect payment option details via the SDK and alongside the "uniqueReference" is required to complete the authorization of the initiated transaction. The transaction reference under the return parameter "uniqueReference" is furthermore required for the following API calls. Beyond this use, it should be persisted if possible, as it enables the identification of the transaction should the need arise at a later stage.
2. Collect Payment Option Details via SDK
The SDK renders a customizable drop down menu, from which the customer can choose their bank. We offer SDKs for the integration into websites as well as mobile applications (Android and iOS).
The authorization token returned by the API method 1.38 Init Authorize which initiated the transaction is used to associate the payment option details collected via the KC Web SDK with the transaction.
Collect Payment Option Details via KC Web SDK
cw.PaymentForm(container,
{
authorizationToken: "https://merch-prod.snd.payu.com/pay/?orderId=TFM{partial omission for brevity}jRFJGp0",
paymentOptionCodes: ["PAYU"],
locale: "en-US" // Optional
});
3. Transmission of Payment Details
The payment system contacts the bank, which was prior chosen by the customer in the dropdown menu rendered by the KC Web SDK. With the payment option details collected, the shopper is redirected to their bank's login webpage.
4. Customer Is Redirected to Their Bank's Login Webpage
After the customer enters their login credentials, the participating bank displays the transaction data in a prefilled payment form.
5. Customer Confirms Transaction
There is no need for further entries by the customer, beside the confirmation of the transaction. This can be done via a TAN procedure (e.g., mobileTAN, pushTAN) or digitally signing the transaction using a 2FA token.
6. Bank Authorizes Transaction
Based on the balance of the customer's account, the bank can approve or decline the transaction. The authorization happens and the appropriate amount is deducted from the account. Immediately after this, the result of the authorization is communicated to the payment service and the shopper is redirected to the previously specified "callbackURL".
7. Complete Authorization
Since the SDK sends the payment details directly to the payment service, where the payment is subsequently processed, you have no knowledge about the current status of the payment and if it got authorized. Therefore, call the API method 1.39 Complete Authorize from your server-side method behind the "callbackURL", which you specified in the SDK.
The transaction authorization is identified by the "uniqueReference" and "authorizationToken" returned initially by the API method 1.38 Init Authorize. Instead of saving these variables on your server-side, pass them via the query string parameters in the "callbackURL".
In some cases e.g., where the user's device loses internet connectivity, the redirect to the specified "callbackURL" does not take place. To prevent the transaction expiring despite it being successful, the API method 1.39 Complete Authorize should automatically be called from your backend 28 minutes after 1.38 Init Authorize has been called, and the payment process completed.
Complete Authorize Request
Path:
POST {baseURL}/payment/{uniqueReference}/completeAuthorize
POST {baseURL}/payment/T9KGCM5AN0y-l9eowgV82Q/completeAuthorize
Header:
Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=
{
"partnerReference": "TEST-363KWVTRWB",
"authorizationToken": "https://merch-prod.snd.payu.com/pay/?orderId=TFM{partial omission for brevity}jRFJGp0",
"localDate": "2020-02-11",
"localTime": "104235"
}
Complete Authorize Response
Status Code:
200 (OK)
Header:
Content-Type: application/json
Accept-Language: en-US
{
"initiatorAccno": "5183630515",
"accno": "5183646503",
"uniqueReference": "t5WpDiwHl0CPcRaMdC75Dg",
"initiationCountryCode": "PL",
"initiationCountryCode3": "POL",
"processedAmount": 3.99,
"processedCurrCode": "PLN",
"statusCode": "AUTHORIZED",
"statusReason": "Authorized",
"paymentProviderResponse": [
{
"id": "8521e8e5-11ac-46cb-b670-0f266592fa02",
"currency": "PLN",
"created": "1581410501766",
"modified": "1581410536917",
"status": "Authorized",
"payment_method": {
"billing_address": {},
"type": "untokenized",
"source_type": "PBL"
},
"provider_configuration": {
"id": "d56aae02-efa8-4e5f-9ee1-7b166d2320b0",
"name": "PayU_PL_Snb_MSh1",
"description": "PayU Merchant 1 - Sandbox PL - PLN",
"created": "1503568002239",
"modified": "1503672766715",
"account_id": "2ffc1077-2562-489b-a93b-0b527302cd69",
"provider_id": "2bb71903-fe65-45fe-8002-1967a43dd64e",
"type": "cc_processor",
"href": "https://api.paymentsos.com/accounts/2ffc1077-2562-489b-a93b-0b527302cd69/provider-configurations/d56aae02-efa8-4e5f-9ee1-7b166d2320b0"
},
"related_resources": {
"authorizations": [
{
"id": "ae3313df-df0a-446b-b7a1-35d9542ca126",
"created": "1581410502215",
"reconciliation_id": "t5WpDiwHl0CPcRaMdC75Dg",
"provider_specific_data": {
"additional_details": {
"bank_name": "payment_wall",
"language": "en"
}
},
"payment_method": {
"billing_address": {},
"type": "untokenized",
"source_type": "PBL"
},
"ip_address": "123.123.123.123",
"originating_purchase_country": "DEU",
"result": {
"status": "Succeed"
},
"provider_data": {
"provider_name": "PayUPoland",
"response_code": "WAITING_FOR_CONFIRMATION",
"raw_response": "{\"order.products.0.quantity\":\"1\",\"order.status\":\"WAITING_FOR_CONFIRMATION\",\"order.products.0.unitPrice\":\"10000\",\"order.additionalDescription\":\"PayU HUB Transaction\",\"properties.0.value\":\"76246243\",\"order.totalAmount\":\"10000\",\"order.merchantPosId\":\"301945\",\"order.description\":\"t5WpDiwHl0CPcRaMdC75Dg\",\"order.products.0.name\":\"wweettPurchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95. Hotline:08001234567.\",\"order.extOrderId\":\"Test Program - t5WpDiwHl0CPcRaMdC75Dg_1581410502018\",\"properties.0.name\":\"PAYMENT_ID\",\"order.notifyUrl\":\"https://api.paymentsos.com/callbacks/payupoland/test/notifications?payment_id=8521e8e5-11ac-46cb-b670-0f266592fa02&x-zooz-request-id=5f67d5cf-fc84-468c-89ab-7e2e6ad01dfc\",\"order.customerIp\":\"123.123.123.123\",\"order.orderCreateDate\":\"2020-02-11T09:41:42.130+01:00\",\"order.currencyCode\":\"PLN\",\"order.orderId\":\"CHZ36C6ZDR200211GUEST000P01\"}",
"transaction_id": "76246243",
"external_id": "CHZ36C6ZDR200211GUEST000P01"
},
"amount": 10000,
"provider_configuration": {
"id": "d56aae02-efa8-4e5f-9ee1-7b166d2320b0",
"name": "PayU_PL_Snb_MSh1",
"description": "PayU Merchant 1 - Sandbox PL - PLN",
"created": "1503568002239",
"modified": "1503672766715",
"account_id": "2ffc1077-2562-489b-a93b-0b527302cd69",
"provider_id": "2bb71903-fe65-45fe-8002-1967a43dd64e",
"type": "cc_processor",
"href": "https://api.paymentsos.com/accounts/2ffc1077-2562-489b-a93b-0b527302cd69/provider-configurations/d56aae02-efa8-4e5f-9ee1-7b166d2320b0"
},
"href": "https://api.paymentsos.com/payments/8521e8e5-11ac-46cb-b670-0f266592fa02/authorizations/ae3313df-df0a-446b-b7a1-35d9542ca126"
}
],
"redirections": [
{
"id": "78b24dbe-9be8-469d-84ae-9e8093dbd4de",
"created": "1581410502198",
"merchant_site_url": "https://example.com/PaymentOption/CompleteAuthorize?id=t5WpDiwHl0CPcRaMdC75Dg",
"url": "https://merch-prod.snd.payu.com/pay/?orderId=CHZ36C6ZDR200211GUEST000P01&token=eyJhbGciOiJIUzI1NiJ9.eyJvcmRlcklkIjoiQ0haMzZDNlpEUjIwMDIxMUdVRVNUMDAwUDAxIiwicG9zSWQiOiJza3lURWxrYSIsImF1dGhvcml0aWVzIjpbIlJPTEVfQ0xJRU5UIl0sImV4cCI6MTU4MTQ5NjkwMiwiaXNzIjoiUEFZVSIsImF1ZCI6ImFwaS1nYXRld2F5Iiwic3ViIjoiUGF5VSBzdWJqZWN0IiwianRpIjoiYzQ4ZDViNWQtOGFlZC00ZWNhLWI3NWQtMzBmOTM4NzA1ZTNmIn0.8CUEuQ2qBw1A3Dv0ED4RjIijqhBhyG9_RKceQTSD6Iw",
"href": "https://api.paymentsos.com/payments/8521e8e5-11ac-46cb-b670-0f266592fa02/redirections/78b24dbe-9be8-469d-84ae-9e8093dbd4de"
}
]
},
"billing_address": {},
"possible_next_actions": [
{
"action": "Void",
"href": "https://api.paymentsos.com/payments/8521e8e5-11ac-46cb-b670-0f266592fa02/voids"
},
{
"action": "Capture",
"href": "https://api.paymentsos.com/payments/8521e8e5-11ac-46cb-b670-0f266592fa02/captures"
}
],
"order": {
"id": "Test Program - t5WpDiwHl0CPcRaMdC75Dg",
"line_items": [
{
"name": "wweettPurchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95. Hotline:08001234567.",
"id": "Test Program",
"quantity": 1,
"unit_price": 10000
}
]
},
"amount": 10000
}
],
"partnerReference": "TEST-363KWVTRWB",
"localDate": "2020-02-11",
"localTime": "104235",
"sysDate": "2020-02-11",
"sysTime": "084236",
"responseCode": "0000",
"responseDescription": "Successful execution.",
"additionalInformation": {
"requestId": "aff2728481a181dc36daedc14055b516"
}
}
Note, that the 1.39 Complete Authorize response includes the internal representation of the Account Number indicated by the parameter Account Number Type.
The response includes the Transaction Status under the return parameter "statusCode", which at this point should be set to "AUTHORIZED" and indicates that the payment was authorized.
Please note if "responseCode": "0035" is returned this indicates the transaction is already "Authorized" and it should be treated as a Successful Response. This can occur if 1.39 Complete Authorize is called twice, or if the authorization was automatically completed 320 minutes (3 days) 1.38 Init Authorize. In such a case it is safe to continue with 1.29 Capture.
8. PaymentsOS Callback
If 1.39 Complete Authorize returns "responseCode": "0006" and "additionalInformation"\"processingStatus" = "Pending", you can initiate intervalled pooling or wait for a callback.
If 1.39 Complete Authorize returns "responseCode": "0035" and "additionalInformation"\"statusCode" = "AUTHORIZED", you can proceed with 1.29 Capture.
If 1.39 Complete Authorize returns "responseCode": "0035" and "additionalInformation"\"statusCode" = "CANCELLED" or "additionalInformation"\"statusCode" = "EXPIRED", the integrating party should notify the user.
The following applies to all existing PaymentsOS integrations taking advantage of payments via Bank Accounts.
The following incrementing polling interval should be followed to call the API Method 1.39 Complete Authorize:
- Immediately on redirect back;
- After 15 minutes;
- After 1 hour;
- After 4 hours;
- After 12 hours;
- After 24 hours,
- After 48 hours;
- After 72 hours;
The Callback will return the following JSON structure to the integrating party:
You can download the above flow diagram from HERE.
Callback Response
{
"notificationType": "AuthorizationFeedback",
"processingStatus": "Status of transaction processing: 'Success' or 'Failed'",
"processingReason": "Description of the transaction processing status",
"transactionStatus": "RECEIVED or AUTHORIZED",
"uniqueReference": "Unique reference of the transaction",
"relatedTransactionReferences": [{
"Array of transaction references of dependent transactions which are updated,
if available. Otherwise, the array is empty."
}]
}
Note, that the 1.39 Complete Authorize response includes the internal representation of the Account Number indicated by the parameter Account Number Type. Additionally, the response includes the transaction status under the status code parameter, which, at this stage, should be set to AUTHORIZED, indicating that the payment has been successfully authorized.
Please also see transaction status handling for non-successful response codes.