Credit Card Payments

Overview

Credit cards can be used for both realtime and scheduled transactions. Due to PCI security requirements, card details must be tokenised client-side before they reach your server; Pinch’s CaptureJS library handles this for you.

This guide shows you the most common workflow for integrating credit card payments.

📘

New here? Make sure you’ve read API Core Concepts first and have your test credentials ready from Test and Live Mode.

Always include pinch-version: 2020.1 in your API requests.

Workflow Summary

1. Tokenise the credit card (client-side, via CaptureJS)
2. Get an access token
3. Create a Payer
4. Realtime payment: charge the card immediately, OR
5. Scheduled payment: queue it for overnight processing
6. Handle the result via webhooks (recommended) or event polling

Detailed Steps

1. Tokenise the credit card

Credit card details must never pass through your own server. Instead, use the Pinch CaptureJS library to capture and tokenise card details directly from the browser.

Embed the script:

<script src="https://cdn.getpinch.com.au/capturejs/pinch.capture.v2.js" integrity="sha384-hglYFSKC4AMA/rAQOGB3OiA8u5ri5F4qNMGgw4I+fggDSlTmPyREcj1J+VGnkAX8" crossorigin="anonymous"></script>

Tokenise the card:

var capture = Pinch.Capture({
    publishableKey: "pk_test_IPA27NRmeTfCawt00h1Zbt9vitpZEPMH"
});

capture.createToken({
    sourceType: "credit-card",
    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) {
    // Send result.token to your server
    document.getElementById("CreditCardToken").value = result.token;
    form.submit();
});

The token (result.token) is a short-lived string you send to your server, which then calls the Pinch API. See CaptureJS Tokenisation for the full reference including bank account tokenisation.

📘

There is also a direct API tokenisation endpoint for native apps. See Tokenise Credit Card. This requires prior approval from Pinch.

2. Get an access token

See Application Authentication for the full details. In short:

POST https://auth.getpinch.com.au/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_APP_ID&client_secret=YOUR_SECRET_KEY

Include the token in every subsequent request:

Authorization: Bearer {token}
pinch-version: 2020.1

3. Create a Payer

Every payment in Pinch must be associated with a Payer (the customer you’re collecting money from). Create one if they don’t already exist.

POST https://api.getpinch.com.au/test/payers
Authorization: Bearer {token}
pinch-version: 2020.1
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "mobile": "0400000000"
}

Save the id from the response (format: pyr_XXXXXXXX); you’ll need it for the payment.

See Create or Update Payer for all available fields.

4a. Execute a realtime payment

To charge the card immediately, use the realtime payment endpoint. This returns a result synchronously.

POST https://api.getpinch.com.au/test/payments/realtime
Authorization: Bearer {token}
pinch-version: 2020.1
Content-Type: application/json

{
  "payerId": "pyr_XXXXXXXX",
  "amount": 1000,
  "description": "Invoice #123",
  "creditCardToken": "{card_token}"
}

The response will include the payment result directly. See Create Realtime Payment.

4b. Schedule a payment

Alternatively, schedule a payment for today or a future date. Scheduled payments are processed overnight (once in the morning, once in the evening).

POST https://api.getpinch.com.au/test/payments
Authorization: Bearer {token}
pinch-version: 2020.1
Content-Type: application/json

{
  "payerId": "pyr_XXXXXXXX",
  "amount": 1000,
  "description": "Invoice #123",
  "creditCardToken": "{card_token}",
  "transactionDate": "2026-08-01"
}

Save the payment id (format: pmt_XXXXXXXX) from the response. See Create or Update Payment.

5. Handle payment outcomes

Since scheduled payments process in the background, you need a way to know when they succeed or fail.

Recommended: Use webhooks. Set up a webhook to receive bank-results, realtime-payment, and transfer events pushed to your server in real time. See Webhooks.

Alternative: Poll the events endpoint. Use List all events and check for:

• bank-results: contains results for all credit card transactions processed that day (both success and failure)
• transfer: confirms funds have been settled to your bank account

Use Get Event to retrieve the full payload for a specific event, then match payment IDs against your records.

📘

For credit cards, both successful and failed payments appear in bank-results. For direct debit, only failures appear there; successes come via transfer.

What to do next

• Webhooks: set up real-time event delivery instead of polling
• Payment Statuses: understand the full payment lifecycle
• CaptureJS Tokenisation: full tokenisation reference
• Plans and Subscriptions: set up recurring billing