Introduction to Saved Cards

If you have returning customers, you can offer them a lot of convenience with CoolPay Saved Cards. With this feature your customer will only have to authorize their credit card once – after that they can pay with just a single click.

We do this by storing the credit card and giving you a reference to that card. You can use this reference for subsequent payments for as long as the credit card is valid.

This is very useful in almost all (if not any) system where the purchaser has registered and identifies themselves (eg. logs in to your shop system) before making the purchase.

CoolPay Saved Cards works out of the box for most merchants – no extra agreement required.

Please note! CoolPay Saved Cards is currently only available with the Clearhaus, Teller and Nets acquirers.

Create and authorize card

  1. Create a new card
  2. Authorize card using a link
  3. Create token

Use the card to complete a payment

  1. Create a new payment
  2. Authorize payment using the token

Examples

Implementation Example


1. Create a new card in CoolPay

POST /cards Create saved card

First step is to create a new card entity in CoolPay.

Example request:

1
2
3
4
5
curl -u ':APIKEY' \
     -H 'content-type:application/json' \
     -H 'Accept-Version:v10' \
     -X POST \
     https://api.coolpay.com/cards

Example response (snippet):

1
2
3
4
5
{
  "id":2886958,
  "merchant_id":1234
  ...
}
PUT /cards/{id}/link Create or update a card link

Next step is to authorize the card.

The recommended way is to request the CoolPay API for a payment link, where your customer can fill in their card information.

Selected parameters. See more in the API documentation.

ParameterDescriptionParameter typeData typeRequired?
idTransaction idpathintegertrue

Example request:

1
2
3
4
5
curl -u ':APIKEY' \
     -H 'content-type:application/json' \
     -H 'Accept-Version:v10' \
     -X PUT \
     https://api.coolpay.com/cards/2886958/link

Example response:

1
2
3
{
  "url":"https://payment.coolpay.com/cards/b4674ca58c6c8a2afeea105fb1b5ca22293a1dc17fa852afa0495010999c2d00"
}

When your customer has filled in the card information using the link, the saved card is now authorized.

No funds are withdrawn from your customer yet.

3. Create token

POST /cards/{id}/tokens Create card token

As of now the customers card is authorized, but no funds have been withdrawed from their account.

Each time the card should be used, your system request the CoolPay API for a token from the Saved Card.

This token can be used once to authorize a payment, subscription or payout.

Example request:

1
2
3
4
5

curl -u ':APIKEY' \
     -H 'content-type:application/json' \
     -H 'Accept-Version:v10' \
     -X POST \
     https://api.coolpay.com/cards/2886958/tokens

Example response (snippet):

1
2
3
4
5
6
{
  "token":"b1467a5e-9927-4574-a065-e704144faae6",
  "is_used":false,
  "created_at":"2017-10-25T13:16:24Z"
  ...
}

The token can now be used to complete a payment, subscription or payout.

1. Create a new payment

POST /payments Create payment

Next step is to create a payment entity in CoolPay

Selected parameters. See more in the API documentation.

ParameterDescriptionParameter typeData typeRequired?
order_idUnique order numberformstringtrue
currencyCurrencyformstringtrue

Example request:

1
2
3
4
5
6
curl -u ':APIKEY \
     -H 'content-type:application/json' \
     -H 'Accept-Version:v10' \
     -X POST \
     -d '{"order_id":"test1ab","currency":"dkk"}' \
     https://api.coolpay.com/cards

Example response (snippet):

1
2
3
4
5
6
7
8
9
10
{
  "id":98648340,
  "merchant_id":1234,
  "order_id":"test1ab",
  "accepted":false,
  "type":"Payment",
  "currency":"DKK",
  "state":"initial"
  ...
}

2. Authorize payment using the token

POST /payments/{id}/authorize Authorize payment

Final step is to authorize the payment using the card token created in step 3.

Selected parameters. See more in the API documentation.

ParameterDescriptionParameter typeData typeReqired?
idTransaction idpathintegertrue
card[token]Card tokenformstringfalse

Example request:

1
2
3
4
5
6
7
curl -u ':APIKEY' \
     -H 'content-type:application/json' \
     -H 'Accept-Version:v10' \
     -X POST \
     -d '{"card":{"token":"b1467a5e-9927-4574-a065-e704144faae6"},
          "amount":1000}'
     https://api.coolpay.com/payment/98648340/authorize

Example response (snippet):

1
2
3
4
5
6
7
8
{
  "id":98648340,
  "merchant_id":1234,
  "order_id":"test1ab",
  "accepted":false,
  "state":"pending"
  ...
}

In the response the payments state is pending, as the authorize is not yet approved or rejected by your acquirer.

Use GET /payments/98648340 to check the payment status, by looking at the accepted parameter.


Implementation Example

Authorizing the credit card

RubyPython

# Use the official coolpay-ruby-client gem
require "coolpay/api/client"
client = CoolPay::API::Client.new(api_key: ENV['YOUR_API_USER_KEY'])

card = client.post("/cards")
link = client.put("/cards/#{card["id"]}/link")

puts link["url"] # Redirect your customer to this URL

# Use the official coolpay-python-client module
from coolpay_api_client import QPClient
secret = ":{0}".format(os.environ['COOLPAY_API_KEY'])
client = QPClient(secret)

card = client.post("/cards")
link = client.put("/cards/%s/link" % card['id'])

print link['url']

Accepting payments using the saved card

RubyPython

# Use the official coolpay-ruby-client gem
require "coolpay/api/client"
client = CoolPay::API::Client.new(api_key: ENV['YOUR_API_USER_KEY'])

tokens  = client.post("/cards/#{card['id']}/tokens")
payment = client.post("/payments",
  :order_id => "0001",
  :currency => "DKK"
)
authorize = client.post("/payments/#{payment['id']}/authorize?synchronized", {
  amount: 100,
  card: { token: tokens['token'] }
})

# Use the official coolpay-python-client module
from coolpay_api_client import QPClient
secret = ":{0}".format(os.environ['COOLPAY_API_KEY'])
client = QPClient(secret)

tokens    = client.post("/cards/%s/tokens" % card['id'])
payment   = client.post("/payment", order_id="0001", currency="DKK")
authorize = client.post("/payments/%s/authorize?synchronized" % payment['id'],
                        amount=100,
                        card={"token": tokens['token']})

Opret bruger