Card payments¶
Provider: PayU
Table of Contents
Introduction¶
User is shown a card form that uses express-payu script to exchange card details for a single-use token
Seller passes the single use token with a set_transaction request to PaySystem
PaySytem initiates a transaction with PayU.
In case a 3ds verification is requeired there will be a redirection uri prepared and send via a notification.User follows the 3ds verification redirection.
When the payment is completed PayU notifies PaySystem and a token for the registered card is prepared.
PaySystem sends the token for the newly registered card to the seller via a notification.
Retreiving Single Use Token¶
When the user deciades to use his payment card the merchant presents to him a card form that facilicates OpenPayU SDK. An example of the form can be find in PayUExpress documentation http://developers.payu.com/en/payu_express.html#payu_express_front_form.
Upon completting the card details in the form OpenPayU sends it over SSL tunel directly to PayU and in response sends back a singleuse-token. The singleuse-token has to be set in set_transaction request as a payment configuration parameters ‘card_singleuse_token’
Starting a new transaction¶
After the users card details are exchanged for single-use token it can be used to make new payment and to be exchanged for a long term token which can be used in later time for charging the registered card.
It is done by sending set_transaction request.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 | curl -X POST \ http://paysystem.tms.onetapi.pl \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json-rpc' \ -d '{ "jsonrpc":"2.0", "id":"example", "method":"set_transaction", "params":{ "trans_ext_id": "12345asdb", "seller_id": <seller-id>, "merchant_id": "1", "user_agreements": 2, "invoice_series_id": 1, "payment":{ "channel_id": <card-registration-payment-channel-id>, "amount": 0, "currency": "PLN", "config": { "card_singleuse_token": "<single-use-token>", "card_store_token": true } }, "articles":[ { "prod_id": "1324", "sap_index": "990001", "vat_rate": 23, "name": "test product", "quantity": 1, "price": 50, "config": [ ] } ], "customer":{ "ext_id": "1234qwera", "name": "test", "firstname": "tester", "lastname": "testowski", "email": "tester@test, "street": "blotna", "city": "krakow", "phone": "48123456789", "postcode": "31-620" }, "client_ip": "127.0.0.1" }' |
channel_id is set to valid value provided by USP for card registration payments team
card_singleuse_token is set to the value of the single use token retreived with the card form
card_store_token if it is set to TRUE the token for card should be saved
3ds verification¶
In case 3ds verification is required, PaySystem will send a notification to an endpoint provided by the seller. The notification will contain the uri where the user has to be redirected to complete the 3ds verification. Afeter the verification is successful, the payment will be perfomed.
1 2 3 4 5 6 7 8 9 10 11 | { "jsonrpc":"2.0", "id":"1error_notification", "method":"error_notification", "params":{ "message":"https://3ds-redirection-uri", "order_id":"<trans-ext-id>", "status":-302, "signature":"c0d820f876317b46b16299b6df503a19498eadd9" } } |
If the seller is not using notifications it is also possible to recivie the 3ds verification redirection by polling ‘get_action_and_data’ method
Card registration and recurring payment¶
Description
Using PayUExpress library http://developers.payu.com/en/payu_express.html a merchant facilitates storing users payment card in PayU and retrieves single-use token.
Merchant calls set_transaction method from PaySystem (paysystem.tms.onetapi.pl) providing singleuse_token, using payment->config structure and setting card_singleuse_token field. There is optional card_store_token parameter available, used if a multi-use token needs to be retrieved and stored for later use (e.g. for usage with a subscription).
PaySystem register payment and call PayU to charge the card referenced by singleuse_token.
After payment is processed by PayU, a callback from the operator is sent to PaySystem.
Upon PayU callback with a payment confirmation, PaySystem calls merchant’s API and provides card_access_key and other card’s details for the future.
Generating a transaction to register cards
The merchant generates a reqest for set_transaction. In the payment section the aa_id is set to the ID of the card registration payment channel. The card registration payment channel ID is provided by USP team. Creating the transaction is asynchronous, and after sending the set_transaction request there is only returned a status if the request has been accepted or not. If the request is accepted, the transaction is processed.
In the payment configuration dictionary are used parameters:
card_singleuse_token : single use token retrieved form PayU
card_store_token : (optiona) if set to ‘true’ the singleuse token will be exchanged for a subscription token and the merchant will receive a card_access_key upon payment notification
The status of the order generation together with card_access_key and card details will be sent to the merchant using a callback from the paysystem notifications system.
It can be either ‘new_payment’ in case the card_registration had been completed or ‘error_notification’ in case the payment agent requires farther 3ds verifiction or the transaction has been canceled.
new_payment params:
“user_id”:
“user_email”: ,
“amount”: ,
“currency”: ,
“order_id”
- “card_details” (optional)
“card_access_key”: access key representing the token for charging the registered card in the future,
“card_issuer”: (VISA, MASTER CARD, MAESTRO),
“card_number_mask”: (eg **** **** **** 1234)
“signature”: sha1(user_id + user_email + amount + currency + order_id + secret_key)
Recurring card payment¶
Payment with the token for the registered card
Merchant calls set_transaction method from PaySystem (paysystem.tms.onetapi.pl) providing card_access_kye, using payment->config structure and setting card_access_key field
After payment is processed by PayU, a callback from the operator is sent to PaySystem.
Upon PayU callback with a payment confirmation, PaySystem calls merchant’s API and provides payment status.
The merchant generates a reqest for ‘set_transaction’. In the payment section the aa_id is set to the ID of the token payment channel. The token payment channel ID is provided by USP team. Creating the transaction is asynchronous, and after sending the set_transaction request there is only returned a status if the request has been accepted or not. If the request is accepted, the transaction is processed.
Trial Card Payment¶
Description
Using PayUExpress library http://developers.payu.com/en/payu_express.html a merchant facilitates storing users payment card in PayU and retrieves single-use token.
Merchant calls set_transaction method from PaySystem (paysystem.tms.onetapi.pl) providing singleuse_token, using payment->config structure and setting card_singleuse_token field.
PaySystem register payment and call PayU to charge the card referenced by singleuse_token.
After payment is processed by PayU, a callback from the operator is sent to PaySystem.
Upon PayU callback with a payment confirmation, PaySystem calls merchant’s API and provides card_access_key and other card’s details for a future use.
Trial card payments are possible only if in PayU management panel ‘Autoodbiór’ for card payments is turned off
Generating a transaction
The merchant generates a reqest for set_transaction. In the payment section the aa_id is set to the ID of the card registration payment channel. The card registration payment channel ID is provided by USP team. Creating the transaction is asynchronous, and after sending the set_transaction request there is only returned a status if the request has been accepted or not. If the request is accepted, the transaction is processed.
In the payment configuration dictionary are used parameters: * card_singleuse_token : single use token retrieved form PayU * it’s required that the article’s price is set to 0
The status of the order generation will be sent to the merchant using a callback from the paysystem notifications system.
It can be either ‘new_payment’ in case the card_registration had been completed or ‘error_notification’ in case the payment agent requires farther 3ds verifiction or the transaction has been canceled.