The charges API allows you to create new payment card charges and retrieve details of previous charges.
Creates a new charge and returns its details. This may be a long-running request.
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 five days.
Default value is
true .
|
Optional metadata |
Arbitrary key-value data to be associated with the charge.{...}
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 for 3D Secure payments.{...}
The necessary 3D Secure keys and values to associate with a charge when presenting it for authorisation. These four values are the minimum required to
demonstrate the charge was authenticated by 3DS. In the case of 3DSv1 the transaction_id should be populated with the XID, for 3DSv2 payments
the transaction_id should be populated with the Directory Server Transaction ID. The CAVV is also known as the cryptogram, AVV or UCAF. The version
number is important for the interpretation of the CAVV and transaction_id values.
|
and one of the following:
card |
The full details of the payment card to be charged {...} .
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. |
customer_token | The token of the customer to be charged, as returned from the customers API. |
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]=2022" \
-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 "three_d_secure[version]=1.0.2" \
-d "three_d_secure[eci]=05" \
-d "three_d_secure[cavv]=AgAAAAAAAIR8CQrXcIhbQAAAAAA=" \
-d "three_d_secure[transaction_id]=MDAwMDAwMDAwMDAwMDAwMzIyNzY=" \
-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_pIQJKMs93GsCc9vLSLevbw",
"scheme": "master",
"display_number": "XXXX-XXXX-XXXX-0000",
"issuing_country": "US",
"expiry_month": 5,
"expiry_year": 2022,
"name": "Roland Robot",
"address_line1": "42 Sevenoaks St",
"address_line2": null,
"address_city": "Lathlain",
"address_postcode": "6454",
"address_state": "WA",
"address_country": "Australia",
"customer_token": null,
"primary": null
},
"transfer": [],
"amount_refunded": 0,
"total_fees": 42,
"merchant_entitlement": 358,
"refund_pending": false,
"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"
}
}
}
422 | invalid_resource |
{...}
|
---|---|---|
400 | card_declined |
{...}
|
400 | insufficient_funds |
{...}
|
400 | processing_error |
{...}
|
400 | suspected_fraud |
{...}
|
400 | expired_card |
{...}
|
400 | lost_card |
{...}
|
400 | stolen_card |
{...}
|
502 | gateway_error |
{...}
|
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.
curl https://test-api.pinpayments.com/1/charges/ch_lfUYEBK14zotCTykezJkfg/void -u your-secret-api-key: -X PUT
{
"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": "Authorisation Voided",
"error_message": null,
"card": {
"token": "card_pIQJKMs93GsCc9vLSLevbw",
"scheme": "master",
"display_number": "XXXX-XXXX-XXXX-0000",
"issuing_country": "US",
"expiry_month": 5,
"expiry_year": 2022,
"name": "Roland Robot",
"address_line1": "42 Sevenoaks St",
"address_line2": null,
"address_city": "Lathlain",
"address_postcode": "6454",
"address_state": "WA",
"address_country": "Australia",
"customer_token": null,
"primary": null
},
"transfer": [],
"amount_refunded": 0,
"total_fees": null,
"merchant_entitlement": null,
"refund_pending": false,
"authorisation_expired": false,
"authorisation_voided": true,
"captured": false,
"captured_at": null,
"settlement_currency": "AUD",
"active_chargebacks": false,
"metadata": {
"OrderNumber": "123456",
"CustomerName": "Roland Robot"
}
}
}
400 | authorisation_expired |
{...}
|
---|---|---|
400 | already_voided |
{...}
|
400 | already_captured |
{...}
|
400 | bad_authorisation |
{...}
|
Captures a previously authorised charge and returns its details. Currently, you can only capture the full amount that was originally authorised.
curl https://test-api.pinpayments.com/1/charges/ch_lfUYEBK14zotCTykezJkfg/capture -u your-secret-api-key: -X PUT
{
"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_pIQJKMs93GsCc9vLSLevbw",
"scheme": "master",
"display_number": "XXXX-XXXX-XXXX-0000",
"issuing_country": "US",
"expiry_month": 5,
"expiry_year": 2022,
"name": "Roland Robot",
"address_line1": "42 Sevenoaks St",
"address_line2": null,
"address_city": "Lathlain",
"address_postcode": "6454",
"address_state": "WA",
"address_country": "Australia",
"customer_token": null,
"primary": null
},
"transfer": [],
"amount_refunded": 0,
"total_fees": 42,
"merchant_entitlement": 358,
"refund_pending": false,
"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"
}
}
}
400 | authorisation_expired |
{...}
|
---|---|---|
400 | already_captured |
{...}
|
400 | bad_authorisation |
{...}
|
400 | invalid_capture_amount |
{...}
|
Returns a paginated list of all charges.
curl https://test-api.pinpayments.com/1/charges -u your-secret-api-key:
{
"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_pIQJKMs93GsCc9vLSLevbw",
"scheme": "master",
"display_number": "XXXX-XXXX-XXXX-0000",
"issuing_country": "US",
"expiry_month": 5,
"expiry_year": 2022,
"name": "Roland Robot",
"address_line1": "42 Sevenoaks St",
"address_line2": null,
"address_city": "Lathlain",
"address_postcode": "6454",
"address_state": "WA",
"address_country": "Australia",
"customer_token": null,
"primary": null
},
"transfer": [
{
"state": "paid",
"paid_at": "2012-06-27T03:10:49Z",
"token": "tfer_j_u-Ef7aO0Y4CuLnGh92rg"
}
],
"amount_refunded": 0,
"total_fees": 42,
"merchant_entitlement": 358,
"refund_pending": false,
"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"
}
}
],
"count": 1,
"pagination": {
"current": 1,
"previous": null,
"next": null,
"per_page": 25,
"pages": 1,
"count": 1
}
}
Returns a paginated list of charges matching the search criteria.
Optional query | Return only charges whose descriptions contain the query or whose amounts exactly match the query. |
---|---|
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 .
|
curl https://test-api.pinpayments.com/1/charges/search?query=test%20charge -u your-secret-api-key:
{
"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_pIQJKMs93GsCc9vLSLevbw",
"scheme": "master",
"display_number": "XXXX-XXXX-XXXX-0000",
"issuing_country": "US",
"expiry_month": 5,
"expiry_year": 2022,
"name": "Roland Robot",
"address_line1": "42 Sevenoaks St",
"address_line2": null,
"address_city": "Lathlain",
"address_postcode": "6454",
"address_state": "WA",
"address_country": "Australia",
"customer_token": null,
"primary": null
},
"transfer": [
{
"state": "paid",
"paid_at": "2012-06-27T03:10:49Z",
"token": "tfer_j_u-Ef7aO0Y4CuLnGh92rg"
}
],
"amount_refunded": 0,
"total_fees": 42,
"merchant_entitlement": 358,
"refund_pending": false,
"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"
}
}
],
"count": 1,
"pagination": {
"current": 1,
"previous": null,
"next": null,
"per_page": 25,
"pages": 1,
"count": 1
}
}
Returns the details of a charge.
curl https://test-api.pinpayments.com/1/charges/ch_lfUYEBK14zotCTykezJkfg -u your-secret-api-key:
{
"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_pIQJKMs93GsCc9vLSLevbw",
"scheme": "master",
"display_number": "XXXX-XXXX-XXXX-0000",
"issuing_country": "US",
"expiry_month": 5,
"expiry_year": 2022,
"name": "Roland Robot",
"address_line1": "42 Sevenoaks St",
"address_line2": null,
"address_city": "Lathlain",
"address_postcode": "6454",
"address_state": "WA",
"address_country": "Australia",
"customer_token": null,
"primary": null
},
"transfer": [
{
"state": "paid",
"paid_at": "2012-06-27T03:10:49Z",
"token": "tfer_j_u-Ef7aO0Y4CuLnGh92rg"
}
],
"amount_refunded": 0,
"total_fees": 42,
"merchant_entitlement": 358,
"refund_pending": false,
"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"
}
}
}
404 | not_found |
{...}
|
---|