Credit Card Payments
A basic workflow for taking Credit Card payments using Pinch
Overview
Credit cards can be used for both realtime and scheduled transactions. Due to tight security requirements, there are a few steps to successfully taking credit card payments.
This guide shows you our most popular workflow for integrating credit card facilities into your products.
Workflow Summary
Here's the list of steps to take to ensure a complete integration.
- Tokenise the Credit Card. See Tokenise Credit Card
- Get an Access Token. See Authentication
- Save a Payer. Capture your customer's credit card information for later use. See Create or Update Payer
- Execute a realtime transaction.
AND/OR
- Schedule a Payment. You can schedule a payment for today, or any time in the future. All payments process overnight. See Save scheduled payment
- Poll for new Events. Events tell you when things happen in the background, such as a payment failing or succeeding. See List all events
- Lookup Bank Results events for transaction result. See Get Event
- Lookup Transfer event for settlement details. See Get Event and List transfer line items
Detailed Steps
1. Tokenise the Credit Card
There are two ways to tokenise a credit card. The primary way is to embed our capture script and then use the tokenisation function to safely capture the credit card details. This allows you to bypass your own server infrastructure and send the credit card details from the user's device directly to us, aleviating you of any PCI requirements.
Method 1: Javascript tokenisation
Embed the script and then call the tokenisation function as demonstrated below.
<script src="https://web.getpinch.com.au/capture/capture.bundle.js"></script>
<script>
var form = document.getElementById("cc-form");
form.addEventListener('submit', function (e) {
e.preventDefault();
var capture = Pinch.Capture({
publishableKey: "pk_test_hof89d7g0987g08d7f9g879"
});
capture.createToken({
cardNumber: document.getElementById("cardNumber").value,
expiryMonth: document.getElementById("expiryMonth").value,
expiryYear: document.getElementById("expiryYear").value,
cvc: document.getElementById("cvc").value,
cardHolderName: document.getElementById("cardHolderName").value
}).then(function(result) {
console.log("Client received token: " + result.token);
document.getElementById("CreditCardToken").value = result.token;
form.submit();
}).catch(function(err) {
document.querySelector("#errors p").innerText = JSON.stringify(err);
console.log("Client error: " + err);
});
});
</script>
The second way to tokenise a credit card is to hit our API directly. This is only allowed from approved merchants. Typically this is used for non web-based technologies, whose code is run directly on user devices, such as native phone apps. This API is not to be called from central servers, as to avoid credit card details flowing through a single point of attack. You may need to prove PCI compliance in some scenarios.
Method 2: API Tokenisation
Directly call Tokenise Credit Card endpoint.
2. Get an Access Token
Our API uses Bearer Authentication, which means you need to ask for an access token to make calls to our API. See Authentication for details of how to fetch one.
Once you have your token, include it as a header with each API call like so:
Authorization: Bearer <token>
3. Save a Payer
All payments within Pinch need to be associated with a Payer. This is the customer that you will be taking funds from.
See Create or Update Payer for the details to submit.
Submit as much information about the payer as you can and be sure to save the Payer ID (pyr_123456789) from the response.
4. Execute a realtime transaction
To take funds immediately from a credit card, use the realtime payment endpoint. Using this endpoint will give you a result in the response.
If you want to schedule payments for the future, you can also follow the steps below.
5. Schedule a Payment
Payments are processed each day, once in the morning and once in the evening. They are sent to the bank overnight and a result is available the next day.
You can submit a payment for a payer using the Save scheduled payment endpoint.
It's a good idea to keep track of the Payment ID (pmt_123456789) that is returned in the response.
6. Poll for new Events
Since the scheduled payments are processed in the background, you'll need a way to be notified when they are either successful or failed (dishonoured). To do this we have an events system for all background processes.
Use the List all events endpoint to retrieve a list of all events. You can look at the type property to determine which kind of event it is. The events you'll want to look at are:
bank-results- Returns a list of payment resultstransfer- Lets you know when a Transfer has been created
You'll use these two events in the next steps.
7. Lookup bank results for payment results
For credit cards, both successful and failed payments will be returned in the bank-results event.
You can use the Get Event endpoint to retrieve the event data, which will contain a list of payment IDs. These will match the payment IDs you saved earlier.
It's up to you to schedule a new payment when one fails.
8. Lookup transfer event for successful payments
A transfer is created whenever there are payments ready to be settled to your merchant bank account. Each transfer contains the details of any successful payments, failed payments, application charges and the fees related to any of these.
Firstly, use the Get Event endpoint to lookup the details of your new transfer event. Specifically, you'll want the Transfer ID (tra_123456789).
Next, fetch the transfer details from the List transfer line items endpoint. This will return a list of Payment IDs and their status (type: 'Settlement' for successful, type: 'Dishonour' for failed.).
You've now successfully integrated Credit Card payments into your system.
Updated about 2 months ago