Integration Guides

Overview Hosted Fields 3D Secure Customers Recurring Payments Marketplaces Apple Pay Google Pay Webhooks Payment Forms Pin.js

Customers

Pin Payments can store customers’ card details securely on file, enabling you to process payments where customers don’t need to re-enter their details each time they make a purchase.

Add a customer

Adding a customer to your Pin Payments account involves two steps.

1. Collect customer’s payment card

Integrating the Hosted Fields interface provides a secure way to collect card details on any web page. It uses Javascript and iframe fields to ensure that payment card data is securely handled by Pin Payments’ servers, rather than your own servers.

Learn how to collect card details using Hosted Fields.

2. Store card details

The Customers API creates a new Customer by accepting the card_token created in the previous step as a parameter.

If successful, the response will include a customer_token parameter, which you can use when you need to process a payment for the customer.

curl https://api.pinpayments.com/1/customer -u your-secret-api-key: \
 -d "email=roland@pinpayments.com" \
 -d "card_token=card_nytGw7koRg23EEp9NTmz9w"

201 Created

{
  "response": {
    "token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "email": "roland@pinpayments.com",
    "first_name": "Roland",
    "last_name": "Robot",
    "phone_number": "1300 364 800",
    "company": "Pin Payments",
    "notes": "Account manager at Pin Payments",
    "created_at": "2023-06-22T06:27:33Z",
    "card": {
      "token": "card_nytGw7koRg23EEp9NTmz9w",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "AU",
      "expiry_month": 5,
      "expiry_year": 2025,
      "name": "Roland Robot",
      "address_line1": "42 Sevenoaks St",
      "address_line2": "",
      "address_city": "Lathlain",
      "address_postcode": "6454",
      "address_state": "WA",
      "address_country": "Australia",
      "network_type": null,
      "network_format": null,
      "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
      "primary": true
    }
  }
}

Charge a customer

With the customer’s billing details stored in your Pin Payments account, you can securely process a charge without needing to prompt the customer for their card details again.

Create a single charge

Provide the customer_token when creating a new charge with the Charges API:

curl https://api.pinpayments.com/1/charges -u your-secret-api-key: \
 -d "amount=400" \
 -d "currency=AUD" \
 -d "description=test charge" \
 -d "customer_token=cus_XZg1ULpWaROQCOT5PdwLkQ" \
 -d "ip_address=203.192.1.172" \
 -d "metadata[OrderNumber]=123456" \
 -d "metadata[CustomerName]=Roland Robot"

201 Created

{
  "response": {
    "token": "ch_lfUYEBK14zotCTykezJkfg",
    "success": true,
    "amount": 400,
    "currency": "AUD",
    "description": "test charge",
    "email": "roland@pinpayments.com",
    "ip_address": "203.192.1.172",
    "created_at": "2023-06-20T03:10:49Z",
    "status_message": "Success",
    "error_message": null,
    "card": {
      "token": "card_nytGw7koRg23EEp9NTmz9w",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "AU",
      "expiry_month": 5,
      "expiry_year": 2025,
      "name": "Roland Robot",
      "address_line1": "42 Sevenoaks St",
      "address_line2": "",
      "address_city": "Lathlain",
      "address_postcode": "6454",
      "address_state": "WA",
      "address_country": "Australia",
      "network_type": null,
      "network_format": null,
      "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
      "primary": true
    },
    "transfer": [],
    "amount_refunded": 0,
    "total_fees": 42,
    "merchant_entitlement": 358,
    "refund_pending": false,
    "authorisation_token": null,
    "authorisation_expired": false,
    "authorisation_voided": false,
    "captured": true,
    "captured_at": "2023-06-20T03:10:49Z",
    "settlement_currency": "AUD",
    "active_chargebacks": false,
    "metadata": {
      "OrderNumber": "123456",
      "CustomerName": "Roland Robot"
    }
  }
}

Subscribe customer to a plan

You can also use the customer_token to create an ongoing subscription for your customer.

Read the Recurring Payments integration guide for more information and examples.

Update a customer’s card

Updating a customer’s card involves two steps, similar to when adding a new customer.

1. Collect customer’s new payment card

Use Hosted Fields to securely collect the customer’s new card details.

2. Store new card details

The Customers API contains a method to update an existing Customer.

You can add the new card_token provided by Hosted Fields to the existing customer, and then set it as the primary_card_token to be used as the default for new charges going forward.