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.
Adding a customer to your Pin Payments account involves two steps.
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.
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"{
"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": "2012-06-22T06:27:33Z",
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"scheme": "master",
"display_number": "XXXX-XXXX-XXXX-0000",
"issuing_country": "US",
"expiry_month": 5,
"expiry_year": 2024,
"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
}
}
}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.
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"{
"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": "2012-06-20T03:10:49Z",
"status_message": "Success",
"error_message": null,
"card": {
"token": "card_nytGw7koRg23EEp9NTmz9w",
"scheme": "master",
"display_number": "XXXX-XXXX-XXXX-0000",
"issuing_country": "US",
"expiry_month": 5,
"expiry_year": 2024,
"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": "2012-06-20T03:10:49Z",
"settlement_currency": "AUD",
"active_chargebacks": false,
"metadata": {
"OrderNumber": "123456",
"CustomerName": "Roland Robot"
}
}
}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.
Updating a customer’s card involves two steps, similar to when adding a new customer.
Use Hosted Fields to securely collect the customer’s 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.