One-click payments

With one-click payments, a returning customer pays with a card they used before. They don't enter their card number again, so checkout is faster and more customers complete their purchase.

One-click payments work in two stages:

1. First transaction. Your customer pays, or verifies their card, and authenticates. Paytrim stores the card in the vault and returns a vault_token.
2. Subsequent transactions. Your customer starts a new purchase. You send the vault_token and the card's CVC instead of the full card details.

Every one-click transaction is started by your customer, who is present in your checkout. To charge a customer who isn't present, for example for a subscription, use recurring payments.

One-click payments are available for card payments. The card payment method must be active for your project.

Step 1: Create the first transactionCopy Anchor Link

Create an order with a credit-card transaction and set one_click_type to first.

Create the order and redirect your customer to the payment_url of the transaction in the response. Your customer enters their card details and authenticates on the hosted payment page. This is the simplest way to store a card.

curl https://api.pay.paytrim.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "merchant_order_id": "HPP-FIRST-001",
    "amount": 1000,
    "currency": "EUR",
    "description": "First one-click payment",
    "return_url": "https://www.example.com/return",
    "transactions": [
      {
        "payment_method": "credit-card",
        "payment_method_details": {
          "one_click_type": "first"
        }
      }
    ],
    "customer": {
      "merchant_customer_id": "CUST-12345",
      "email_address": "john.smith@example.com",
      "first_name": "John",
      "last_name": "Smith",
      "address_type": "billing",
      "address": "100 Main St",
      "postal_code": "SW1A 0AA",
      "country": "GB",
      "city": "London",
      "ip_address": "198.51.100.1"
    }
  }'

Step 2: Store the vault tokenCopy Anchor Link

When the order is completed, retrieve it to get the vault_token:

curl https://api.pay.paytrim.com/v1/orders/9f7c1a52-3c1e-4c8b-a1d4-2f5b8e6d0c31/ \
  --user "$API_KEY:"

The token is in the payment_method_details of the transaction. The response is shortened:

{
  "id": "9f7c1a52-3c1e-4c8b-a1d4-2f5b8e6d0c31",
  "status": "completed",
  "transactions": [
    {
      "id": "3b2e8f40-7d5c-4a91-b6e2-0c9f1d7a4e58",
      "payment_method": "credit-card",
      "payment_method_details": {
        "card_expiry": "012028",
        "cardholder_name": "John Smith",
        "one_click_type": "first",
        "truncated_pan": "************1111",
        "vault_token": "e72f7733-9e41-4fc3-968a-9d6b52081ddf"
      },
      "status": "completed"
    }
  ]
}

Store the vault_token securely and link it to the customer in your system. Also store the transaction id if you want to use it instead of the token (see below). Show your customer the truncated_pan, so they recognise the card next time.

Step 3: Create subsequent transactionsCopy Anchor Link

When your customer pays again, create an order with one_click_type set to one-click. Send the stored vault_token and the CVC your customer enters in your checkout:

curl https://api.pay.paytrim.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "merchant_order_id": "ONECLICK-002",
    "amount": 2500,
    "currency": "EUR",
    "description": "One-click purchase",
    "return_url": "https://www.example.com/return",
    "transactions": [
      {
        "payment_method": "credit-card",
        "payment_method_details": {
          "one_click_type": "one-click",
          "vault_token": "e72f7733-9e41-4fc3-968a-9d6b52081ddf",
          "cvc": "123"
        }
      }
    ],
    "customer": {
      "merchant_customer_id": "CUST-12345",
      "ip_address": "198.51.100.1"
    }
  }'

Instead of the vault_token, you can send the first_transaction_id: the id of the transaction from step 1.

The response contains a payment_url. Redirect your customer to it, so they can authenticate if their bank asks for it. When the payment succeeds, the order status changes to completed. Confirm the result with a webhook and a status request, as for any other payment.

Visa Account Name InquiryCopy Anchor Link

Visa Account Name Inquiry (ANI) checks whether the cardholder name your customer enters matches the name the issuer has on file. It runs automatically when all of these apply to the first transaction:

• The amount is 0.
• Your customer pays with a Visa card.
• Your customer enters the cardholder name.

The result is in the payment_method_details of the transaction:

{
  "ani_results": {
    "status": "00",
    "status_description": "ANI successfully performed",
    "match": "01",
    "match_description": "full match"
  }
}