API Reference

Charges API

The charges API allows you to create new payment card charges and retrieve details of previous charges.

POST /charges

Creates a new charge and returns its details. This may be a long-running request.

Parameters

email The email address of the purchaser.
description A description of the item purchased (e.g. 500g of single origin beans).
amount The amount to charge in the currency’s base unit (e.g. cents for AUD, yen for JPY). There is a minimum charge amount for each currency; refer to the documentation on supported currencies.
ip_address The IP address of the person submitting the payment.
Optional currency The three-character ISO 4217 currency code of one of our supported currencies, e.g. AUD or USD. Default value is AUD.
Optional capture Whether to immediately capture the charge (true or false). If false, we will attempt to create an authorisation; if this is successful, you can capture at a later time. Authorised charges automatically expire after seven days. Default value is true.
Optional reference A custom text string which will be displayed in place of the default descriptor on the customer's bank statement.
Optional metadata Arbitrary key-value data to be associated with the charge.{...}
{
  "OrderNumber": "123456",
  "CustomerName": "Roland Robot",
  "order taken by": "Rachel",
  "Location": "Lat:-31.950527, Long:115.860457",
  "time_order_completed": "01 JUL 2016 10:35:03 UTC+08:00"
}
A metadata item is composed of a key (a string with a maximum length of 50 characters) and a value (a string with a maximum length of 500 characters). You can supply up to 25 metadata items per charge. Pin Payments does not display metadata to your customers.
Optional three_d_secure Information required to enable 3D Secure on payments.{...}
{
  "enabled": true,
  "fallback_ok": true,
  "callback_url": "https://yoursite.com/authentication_complete"
}
Only enabled and callback_url are required. Use fallback_ok to allow the charge to proceed in situations where 3D Secure is unavailable, such as when the provided card does not support 3D Secure. In the case of a fallback, you will not benefit from the dispute liability shift provided by 3D Secure.
Optional platform_adjustment Specify an amount to withhold from the merchant entitlement to collect as revenue for your platform.{...}
{
  "amount": 30,
  "currency": "AUD"
}

and one of the following:

card The full details of the payment card to be charged {...}. 
{
  "number": "5520000000000000",
  "expiry_month": "05",
  "expiry_year": "2026",
  "cvc": "123",
  "name": "Roland Robot",
  "address_line1": "42 Sevenoaks St",
  "address_city": "Lathlain",
  "address_postcode": "6454",
  "address_state": "WA",
  "address_country": "Australia"
}
See the cards API for a description of each card parameter.
card_token The token of the card to be charged, as returned from the cards API or customers API.
payment_source_token The token of the payment source to be charged, as returned from the payment_sources API.
customer_token The token of the customer to be charged, as returned from the customers API.

Example

curl https://test-api.pinpayments.com/1/charges -u your-secret-api-key: \
 -d "amount=400" \
 -d "currency=AUD" \
 -d "description=test charge" \
 -d "email=roland@pinpayments.com" \
 -d "ip_address=203.192.1.172" \
 -d "card[number]=5520000000000000" \
 -d "card[expiry_month]=05" \
 -d "card[expiry_year]=2026" \
 -d "card[cvc]=123" \
 -d "card[name]=Roland Robot" \
 -d "card[address_line1]=42 Sevenoaks St" \
 -d "card[address_line2]=" \
 -d "card[address_city]=Lathlain" \
 -d "card[address_postcode]=6454" \
 -d "card[address_state]=WA" \
 -d "card[address_country]=Australia" \
 -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_pIQJKMs93GsCc9vLSLevbw",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "AU",
      "expiry_month": 5,
      "expiry_year": 2026,
      "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": null,
      "primary": null
    },
    "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"
    }
  }
}

3D Secure enabled response

202 Accepted 
{
  "response": {
    "token": "ch_lfUYEBK14zotCTykezJkfg",
    "status_message": "Pending",
    "redirect_url": "https://sandbox.checkout.com/api2/v2/3ds/acs/sid_feixbit6us3utfedjulm6egnsu"
  }
}

Error Responses

422 invalid_resource {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": [
    {
      "code": "description_invalid",
      "message": "Description can't be blank",
      "param": "description"
    }
  ]
}
400 card_declined {...} 
{
  "error": "card_declined",
  "error_description": "The card was declined",
  "charge_token": "ch_lfUYEBK14zotCTykezJkfg"
}
400 insufficient_funds {...} 
{
  "error": "insufficient_funds",
  "error_description": "There are not enough funds available to process the requested amount",
  "charge_token": "ch_lfUYEBK14zotCTykezJkfg"
}
400 processing_error {...} 
{
  "error": "processing_error",
  "error_description": "An error occurred while processing the card",
  "charge_token": "ch_lfUYEBK14zotCTykezJkfg"
}
400 suspected_fraud {...} 
{
  "error": "suspected_fraud",
  "error_description": "The transaction was flagged as possibly fraudulent and subsequently declined",
  "charge_token": "ch_lfUYEBK14zotCTykezJkfg"
}
400 expired_card {...} 
{
  "error": "expired_card",
  "error_description": "The card has expired",
  "charge_token": "ch_lfUYEBK14zotCTykezJkfg"
}
400 lost_card {...} 
{
  "error": "lost_card",
  "error_description": "The transaction was declined as the card has been reported lost by the card issuer",
  "charge_token": "ch_lfUYEBK14zotCTykezJkfg"
}
400 stolen_card {...} 
{
  "error": "stolen_card",
  "error_description": "The transaction was declined as the card has been reported stolen by the card issuer",
  "charge_token": "ch_lfUYEBK14zotCTykezJkfg"
}
400 token_already_used {...} 
{
  "error": "token_already_used",
  "error_description": "Token already used. Card tokens can only be used once, to create a charge or assign a card to a customer"
}
502 gateway_error {...} 
{
  "error": "gateway_error",
  "error_description": "An upstream error occurred while processing the transaction. Please try again.",
  "charge_token": "ch_lfUYEBK14zotCTykezJkfg"
}

PUT /charges/charge-token/void

Voids a previously authorised charge and returns its details. This will return the reserved funds to the cardholder, and capture will no longer be possible.

Example

curl https://test-api.pinpayments.com/1/charges/ch_lfUYEBK14zotCTykezJkfg/void -u your-secret-api-key: -X PUT
200 OK 
{
  "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": "Authorisation Voided",
    "error_message": null,
    "card": {
      "token": "card_pIQJKMs93GsCc9vLSLevbw",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "AU",
      "expiry_month": 5,
      "expiry_year": 2026,
      "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": null,
      "primary": null
    },
    "transfer": [],
    "amount_refunded": 0,
    "total_fees": null,
    "merchant_entitlement": null,
    "refund_pending": false,
    "authorisation_token": null,
    "authorisation_expired": false,
    "authorisation_voided": true,
    "captured": false,
    "captured_at": null,
    "settlement_currency": "AUD",
    "active_chargebacks": false,
    "metadata": {
      "OrderNumber": "123456",
      "CustomerName": "Roland Robot"
    }
  }
}

Error Responses

400 authorisation_expired {...} 
{
  "error": "authorisation_expired",
  "error_description": "The authorisation has expired and can not be captured"
}
400 already_voided {...} 
{
  "error": "already_voided",
  "error_description": "The authorisation has already been voided"
}
400 already_captured {...} 
{
  "error": "already_captured",
  "error_description": "This authorisation has already been captured"
}
400 bad_authorisation {...} 
{
  "error": "bad_authorisation",
  "error_description": "The authorisation failed and can not be captured"
}

PUT /charges/charge-token/capture

Captures a previously authorised charge and returns its details. Currently, you can only capture the full amount that was originally authorised.

Example

curl https://test-api.pinpayments.com/1/charges/ch_lfUYEBK14zotCTykezJkfg/capture -u your-secret-api-key: -X PUT
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_pIQJKMs93GsCc9vLSLevbw",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "AU",
      "expiry_month": 5,
      "expiry_year": 2026,
      "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": null,
      "primary": null
    },
    "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"
    }
  }
}

Error Responses

400 authorisation_expired {...} 
{
  "error": "authorisation_expired",
  "error_description": "The authorisation has expired and can not be captured"
}
400 already_captured {...} 
{
  "error": "already_captured",
  "error_description": "This authorisation has already been captured"
}
400 bad_authorisation {...} 
{
  "error": "bad_authorisation",
  "error_description": "The authorisation failed and can not be captured"
}
400 invalid_capture_amount {...} 
{
  "error": "invalid_capture_amount",
  "error_description": "You must capture the full amount that was authorised",
  "charge_token": "ch_lfUYEBK14zotCTykezJkfg"
}

GET /charges

Returns a paginated list of all charges.

Example

curl https://test-api.pinpayments.com/1/charges -u your-secret-api-key:
200 OK 
{
  "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_pIQJKMs93GsCc9vLSLevbw",
        "scheme": "master",
        "display_number": "XXXX-XXXX-XXXX-0000",
        "issuing_country": "AU",
        "expiry_month": 5,
        "expiry_year": 2026,
        "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": null,
        "primary": null
      },
      "transfer": [
        {
          "state": "paid",
          "paid_at": "2023-06-27T03:10:49Z",
          "token": "tfer_j_u-Ef7aO0Y4CuLnGh92rg"
        }
      ],
      "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"
      }
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

GET /charges/search

Returns a paginated list of charges matching the search criteria.

Optional query Return only charges whose fields match the query. Fields covered include description, email, metadata, cardholder name, currency, amount (exact), charge token (exact), card token (exact), refund token (exact), and customer token (exact).
Optional start_date Return only charges created on or after this date (e.g. 2012/12/25).
Optional end_date Return only charges created before this date (e.g. 2013/12/25).
Optional sort The field used to sort the charges (created_at or amount). Default value is created_at.
Optional direction The direction in which to sort the charges (1 for ascending or -1 for descending). Default value is 1.

Example

curl https://test-api.pinpayments.com/1/charges/search -u your-secret-api-key: -X GET \
 -d "query=test%20charge"
200 OK 
{
  "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_pIQJKMs93GsCc9vLSLevbw",
        "scheme": "master",
        "display_number": "XXXX-XXXX-XXXX-0000",
        "issuing_country": "AU",
        "expiry_month": 5,
        "expiry_year": 2026,
        "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": null,
        "primary": null
      },
      "transfer": [
        {
          "state": "paid",
          "paid_at": "2023-06-27T03:10:49Z",
          "token": "tfer_j_u-Ef7aO0Y4CuLnGh92rg"
        }
      ],
      "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"
      }
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

GET /charges/charge-token

Returns the details of a charge.

Example

curl https://test-api.pinpayments.com/1/charges/ch_lfUYEBK14zotCTykezJkfg -u your-secret-api-key:
200 OK 
{
  "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_pIQJKMs93GsCc9vLSLevbw",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "AU",
      "expiry_month": 5,
      "expiry_year": 2026,
      "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": null,
      "primary": null
    },
    "transfer": [
      {
        "state": "paid",
        "paid_at": "2023-06-27T03:10:49Z",
        "token": "tfer_j_u-Ef7aO0Y4CuLnGh92rg"
      }
    ],
    "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"
    }
  }
}

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

GET /charges/verify?session_token=session-token

Verify the result of a 3D Secure enabled charge.

For more information about 3D Secure, see the 3D Secure integration guide.

Example

curl https://api.pinpayments.com/1/charges/verify -u your-secret-api-key: -X GET \
 -d "session_token=se_sGt9PuNYfVzJqTSLP2CV8g"
200 OK 
{
  "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_pIQJKMs93GsCc9vLSLevbw",
      "scheme": "master",
      "display_number": "XXXX-XXXX-XXXX-0000",
      "issuing_country": "AU",
      "expiry_month": 5,
      "expiry_year": 2026,
      "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": null,
      "primary": null
    },
    "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"
    }
  }
}

Error Responses

403 transaction_forbidden {...} 
{
  "error": "transaction_forbidden",
  "error_description": "Your account does not have permission to perform this transaction"
}
404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}
422 three_d_secure_unavailable {...} 
{
  "error": "three_d_secure_unavailable",
  "error_description": "3DS is not available with this configuration"
}
Pin Payments acknowledges the Traditional Owners and Custodians of the Country throughout Australia and recognises their continuing connection to land, water and community.
We pay our respects to Aboriginal and Torres Strait Islander cultures, and to Elders past and present.