Authorisations API Beta

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

POST /authorisations

Creates a new authorisation 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 authorise in the currency’s base unit (e.g. cents for AUD, yen for JPY).
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 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 authorisation.`{...}` `{ "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 authorisation. Pin Payments does not display metadata to your customers.

and one of the following:

card	The full details of the payment card to be authorised `{...}`. `{ "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 authorised, as returned from the cards API or customers API.
customer_token	The token of the customer to be authorised, as returned from the customers API.

Example

curl https://test-api.pinpayments.com/1/authorisations -u your-secret-api-key: \
 -d "amount=400" \
 -d "currency=AUD" \
 -d "description=test authorisation" \
 -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": "auth_NRzYklT8z3p0yiozsXEAIg",
    "success": true,
    "amount": 400,
    "amount_captured": 0,
    "amount_remaining": 400,
    "currency": "AUD",
    "description": "test authorisation",
    "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
    },
    "settlement_currency": "AUD",
    "expired": false,
    "voided": false,
    "voided_at": null,
    "capturable": true,
    "metadata": {
      "OrderNumber": "123456",
      "CustomerName": "Roland Robot"
    }
  }
}

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", "authorisation_token": "auth_NRzYklT8z3p0yiozsXEAIg" }`
400	insufficient_funds	`{...}` `{ "error": "insufficient_funds", "error_description": "There are not enough funds available to process the requested amount", "authorisation_token": "auth_NRzYklT8z3p0yiozsXEAIg" }`
400	processing_error	`{...}` `{ "error": "processing_error", "error_description": "An error occurred while processing the card", "authorisation_token": "auth_NRzYklT8z3p0yiozsXEAIg" }`
400	suspected_fraud	`{...}` `{ "error": "suspected_fraud", "error_description": "The transaction was flagged as possibly fraudulent and subsequently declined", "authorisation_token": "auth_NRzYklT8z3p0yiozsXEAIg" }`
400	expired_card	`{...}` `{ "error": "expired_card", "error_description": "The card has expired", "authorisation_token": "auth_NRzYklT8z3p0yiozsXEAIg" }`
400	lost_card	`{...}` `{ "error": "lost_card", "error_description": "The transaction was declined as the card has been reported lost by the card issuer", "authorisation_token": "auth_NRzYklT8z3p0yiozsXEAIg" }`
400	stolen_card	`{...}` `{ "error": "stolen_card", "error_description": "The transaction was declined as the card has been reported stolen by the card issuer", "authorisation_token": "auth_NRzYklT8z3p0yiozsXEAIg" }`
502	gateway_error	`{...}` `{ "error": "gateway_error", "error_description": "An upstream error occurred while processing the transaction. Please try again.", "authorisation_token": "auth_NRzYklT8z3p0yiozsXEAIg" }`

PUT /authorisations/auth-token/void

Voids a previously created authorisation 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/authorisations/auth_NRzYklT8z3p0yiozsXEAIg/void -u your-secret-api-key: -X PUT

200 OK

{
  "response": {
    "token": "auth_NRzYklT8z3p0yiozsXEAIg",
    "success": true,
    "amount": 400,
    "amount_captured": 0,
    "amount_remaining": 400,
    "currency": "AUD",
    "description": "test authorisation",
    "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
    },
    "settlement_currency": "AUD",
    "expired": false,
    "voided": true,
    "voided_at": "2023-06-20T03:11:49Z",
    "capturable": 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" }`

POST /authorisations/auth-token/charges

Captures the authorised funds and returns details of the charge.

Parameters

amount	The amount to authorise in the currency’s base unit (e.g. cents for AUD, yen for JPY).

Example

curl https://test-api.pinpayments.com/1/authorisations/auth_NRzYklT8z3p0yiozsXEAIg/charges -u your-secret-api-key: \
 -d "amount=250"

200 OK

{
  "response": {
    "token": "ch_IA-dSSgBc59DDWOp0Y9Xcw",
    "success": true,
    "amount": 250,
    "currency": "AUD",
    "description": "test authorisation",
    "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": 34,
    "merchant_entitlement": 216,
    "refund_pending": false,
    "authorisation_token": "auth_NRzYklT8z3p0yiozsXEAIg",
    "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

422	invalid_resource	`{...}` `{ "error": "invalid_resource", "error_description": "One or more parameters were missing or invalid", "messages": [ { "param": "amount", "code": "amount_invalid", "message": "Amount is not a number" }, { "param": "amount", "code": "amount_invalid", "message": "Amount must be at least 100 ($1.00 AUD)" } ] }`
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" }`

GET /authorisations

Returns a paginated list of all authorisations.

Example

curl https://test-api.pinpayments.com/1/authorisations -u your-secret-api-key:

200 OK

{
  "response": [
    {
      "token": "auth_NRzYklT8z3p0yiozsXEAIg",
      "success": true,
      "amount": 400,
      "amount_captured": 0,
      "amount_remaining": 400,
      "currency": "AUD",
      "description": "test authorisation",
      "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
      },
      "settlement_currency": "AUD",
      "expired": false,
      "voided": false,
      "voided_at": null,
      "capturable": true,
      "metadata": {
        "OrderNumber": "123456",
        "CustomerName": "Roland Robot"
      }
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

GET /authorisation/auth-token

Returns the details of a authorisation.

Example

curl https://test-api.pinpayments.com/1/authorisations/auth_NRzYklT8z3p0yiozsXEAIg -u your-secret-api-key:

200 OK

{
  "response": {
    "token": "auth_NRzYklT8z3p0yiozsXEAIg",
    "success": true,
    "amount": 400,
    "amount_captured": 0,
    "amount_remaining": 400,
    "currency": "AUD",
    "description": "test authorisation",
    "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
    },
    "settlement_currency": "AUD",
    "expired": false,
    "voided": false,
    "voided_at": null,
    "capturable": true,
    "metadata": {
      "OrderNumber": "123456",
      "CustomerName": "Roland Robot"
    }
  }
}

Error Responses

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

API Reference

Authorisations API Beta

POST /authorisations

Parameters

Example

Error Responses

PUT /authorisations/auth-token/void

Example

Error Responses

POST /authorisations/auth-token/charges

Parameters

Example

Error Responses

GET /authorisations

Example

GET /authorisation/auth-token

Example

Error Responses