Card payments¶

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.

 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"
  }'

 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"
   }
}

Card registration and recurring payment¶

Description

1. 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.

2. 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).

3. PaySystem register payment and call PayU to charge the card referenced by singleuse_token.

4. After payment is processed by PayU, a callback from the operator is sent to PaySystem.

5. 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

1. 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

2. After payment is processed by PayU, a callback from the operator is sent to PaySystem.

3. 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.