Skip to main content
A customer is one of your workspace’s customers: the same record your team sees under Customers in the Payra dashboard. Payment methods saved on a customer can be charged again without the buyer typing the card, and payments made with them are filed on that customer in the dashboard. Create each buyer as a customer from your server, with your own id for them (your user id, for example) as reference. You can keep Payra’s id with your user, or skip that and look the customer up by reference whenever you need it.
1

Create the customer

Call it when the buyer signs up, or the first time they pay with you. Calling it again later is safe (see below).
Response
Every field is optional. reference is your id for the buyer, up to 100 characters, unique in your workspace. phone is in E.164 format (+1 and ten digits for a US number). name is the name the dashboard shows; when you leave it out, the email is used as the name, or the reference when there is no email either, and name returns that.
2

Find the customer again by your id

The list holds that one customer, or none. With Payra’s id, GET /customers/{id} reads it directly.

​
Creating again is safe

When a customer of your workspace already has the reference you send, POST /customers creates nothing: it returns that customer, unchanged, with 200 instead of 201, and ignores the other fields you sent. So you can call it at every sign-up or checkout without looking the buyer up first, and a retry after a timeout, or two requests arriving at the same time, never makes a second customer. Without a reference, every call creates a new customer.

​
Saving and reusing a card

A new buyer, or one paying with a new card:
  1. POST /customers with your user id as reference, if you have not already.
  2. Create a payment method session with that customer, and let Elements collect the card. Saving needs the billing postal code: collect it on your page and pass it when Elements confirms the session.
  3. Create the payment method with account_holder_authorization: true, your statement that the buyer agreed to keep the card on file. Payra verifies the card with the processor and saves it on the customer; the method reads usage: saved.
  4. Charge it for the order.
If your checkout lets the buyer choose whether to keep the card, create the session with their customer either way and send the choice in step 3: account_holder_authorization: true to save it, or usage: "one_time" to charge it once without saving. The payment is filed on the customer in both cases, and the buyer can change their mind without the card fields being reset. To check a card before the buyer buys anything, stop after step 3. No payment is created. The verification is a small authorization that the processor voids at once (on Dhango, $1.00); it may still show on the buyer’s statement as pending for a short while. A returning buyer:
  1. GET /customers?reference=… to find their customer (or use the id you kept).
  2. List their saved payment methods and show them.
  3. Charge the one they pick with POST /payments, passing its payment_method, and customer if you like.
A buyer who deletes a card in your store: detach it, so it can no longer be charged and leaves their file in the dashboard. Buyers who already had an account with you before you started using Payra need nothing done in advance. The first time one pays by card, POST /customers with their user id creates their customer on the spot, and they enter the card once. Cards saved with a previous processor stay with that processor.

​
What else comes with a customer

  • Receipts from Payra. When the customer has an email and the workspace’s Email payment receipts to customers setting is on, charging one of their saved payment methods emails them Payra’s payment receipt. Turn the setting off if you send your own. See Payments.
  • The dashboard. Your team sees the customer, their saved cards and their payments, and can remove a card there too; its payment method then reads detached.
  • No environment. Customers belong to the workspace, not to sandbox or live: a sandbox key and a live key read the same ones. Payment methods do belong to one environment, so a customer’s sandbox cards are never listed or charged with a live key.
Customers created in the dashboard, or synced from an ERP, can be read and listed too; their reference is null. A workspace whose customers come from an ERP integration cannot create them through the API: POST /customers answers 403 customers_managed_by_erp.

​
Scopes and errors

Creating needs customers:write; reading and listing need customers:read. The list runs newest first and pages with limit and starting_after.