Recurring payments

Charge a stored card for subscriptions and other repeated payments, without your customer being present.

Use recurring payments for subscriptions, instalments and other repeated charges. They cover two kinds of series:

`schedule_type`	Use it for	Example
`scheduled`	Charges at fixed intervals	A monthly subscription
`unscheduled`	Charges at moments that vary	Automatic top-ups when a balance runs low

Recurring payments work in two stages:

First transaction. Your customer pays, or verifies their card, and authenticates. Paytrim stores the card in the vault and returns a vault_token.
Subsequent transactions. You charge the stored card whenever a payment is due. Your customer isn't present and doesn't need to do anything.

Keep these rules in mind:

A recurring series is valid for at most one year. After that, start a new series with a new first transaction.
The amount of the first transaction can differ from the subsequent ones.
For a payment that your customer starts themselves, such as a faster checkout, use one-click payments instead.

Apple Pay and Google Pay support recurring payments as well, with a few differences. See Recurring payments with Apple Pay and Recurring payments with Google Pay.

Step 1: Create the first transaction

Create an order with a credit-card transaction and set these fields in payment_method_details:

Field	Value
`recurring_type`	`first`
`schedule_type`	`scheduled` or `unscheduled`

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.

curl https://api.pay.paytrim.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "merchant_order_id": "SUB-001",
    "amount": 1000,
    "currency": "EUR",
    "description": "Subscription setup",
    "return_url": "https://www.example.com/return",
    "transactions": [
      {
        "payment_method": "credit-card",
        "payment_method_details": {
          "recurring_type": "first",
          "schedule_type": "scheduled"
        }
      }
    ],
    "customer": {
      "merchant_customer_id": "CUST-ABCDE",
      "email_address": "jane.doe@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "address_type": "billing",
      "address": "123 Abbey Road",
      "postal_code": "NW8 9AY",
      "country": "GB",
      "city": "London",
      "ip_address": "203.0.113.10"
    }
  }'

Verify a card without charging it

To only store and verify the card, set amount to 0 in the first transaction. Your customer still authenticates, but isn't charged.

Step 2: Store the vault token

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

curl https://api.pay.paytrim.com/v1/orders/5d2a9c84-1f6b-4e37-9a0d-7c3e8b1f2a96/ \
  --user "$API_KEY:"

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

{
  "id": "5d2a9c84-1f6b-4e37-9a0d-7c3e8b1f2a96",
  "status": "completed",
  "transactions": [
    {
      "id": "a41f7e2c-8b3d-4c95-9e60-1d7b2f8c3a04",
      "payment_method": "credit-card",
      "payment_method_details": {
        "card_expiry": "122029",
        "cardholder_name": "Jane Doe",
        "recurring_type": "first",
        "schedule_type": "scheduled",
        "truncated_pan": "************4444",
        "vault_token": "0c8fd8ab-25ec-4109-ac8f-495804aa5026"
      },
      "status": "completed"
    }
  ]
}

Store the vault_token and the transaction id securely, and link them to your customer's subscription. You need one of them for every subsequent charge.

Step 3: Charge subsequent payments

When a payment is due, create an order with recurring_type set to recurring. Reference the series with the first_transaction_id, the id of the transaction from step 1:

curl https://api.pay.paytrim.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "merchant_order_id": "SUB-001-CYCLE-02",
    "amount": 4000,
    "currency": "EUR",
    "description": "Monthly subscription",
    "webhook_url": "https://www.example.com/webhook",
    "transactions": [
      {
        "payment_method": "credit-card",
        "payment_method_details": {
          "recurring_type": "recurring",
          "first_transaction_id": "a41f7e2c-8b3d-4c95-9e60-1d7b2f8c3a04"
        }
      }
    ],
    "customer": {
      "merchant_customer_id": "CUST-ABCDE",
      "ip_address": "203.0.113.10"
    }
  }'

Instead of the first_transaction_id, you can send the vault_token from step 2.

The payment is processed without your customer. There's no payment_url to redirect to. Follow the result with a webhook and a status request.

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

`status`	Meaning
`00`	ANI was performed.
`01`	ANI was requested but not performed.
`02`	ANI was requested but the issuer doesn't support it.

`match`	Meaning
`01`	Full match
`50`	Partial match
`99`	No match

Recurring payments

Step 1: Create the first transactionCopy Anchor Link

Step 2: Store the vault tokenCopy Anchor Link

Step 3: Charge subsequent paymentsCopy Anchor Link

Visa Account Name InquiryCopy Anchor Link

On this page

Step 1: Create the first transaction

Step 2: Store the vault token

Step 3: Charge subsequent payments

Visa Account Name Inquiry