Charge or Tokenise a Credit Card

Our Credit Card API handles secure storage, tokenisation, and charging of credit and debit cards.

Pay Advantage is PCI level 1 compliant and so you can be assured that we take a world class approach to securing and storing all financial information that goes through our system.

You will need to be responsible for how you handle this information in your own system but when we can we will give guidelines around what you should and shouldn't store. If you want to learn more about PCI compliance and how to keep your business and systems secure, you can read more here.

Endpoints

GET     '/credit_cards/{code}'
 GET     '/credit_cards/{code}/charges'
 GET     '/credit_cards/charges/{externalid}'
 GET     '/calculator/fees/realtime_credit_card?amount={value}'
 POST    '/credit_cards'
 POST    '/credit_cards/{code}/charges'

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/credit_cards_post-1

Credit cards can be stored and used later for Batch Debiting and individual payments. They must always be stored against an existing customer. You should never store the credit card number (unless hashed) and in no instance should the CVN ever be saved.

After you post this request the body will return a code which will be used to call the tokenised card for processing payments and GET requests. This code can be stored as it will only return hashed details. When passed through during tokenisation we sometimes use the CVN to verify the card before discarding.

View Test Credit Cards that can be used in Sandbox to safely test your API without using real card details.

Example Request

curl -L -X POST 'https://api.payadvantage.com.au/v3/credit_cards' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 -d '{
       "CardHolder": "Bob Smith",
       "CardNumber": "4200000000000000",
       "CVN": "123",
       "ExpiryMonth": 1,
       "ExpiryYear": 2022,
       "Customer": { 
         "Code": "C12345"
       }
     }'

Example Responses

STATUS 201 // Successful
    
{
	"Code": "CC1234",
	"CardHolder": "Bob Smith",
	"Expiry": "09/2022",
	"DisplayHash": "XXXX-XXXX-XXXX-1111",
	"CardType": "visa",
	"Customer": {
		"Code": "C12345"
	}
}

STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [ 
		"Error message."
	]
}

Request Parameters

CardHolder string Required
The full name of the Cardholder this card belongs too i.e. "{FirstName} {MiddleName} {LastName}"
CardNumber string Required
The full card number to be tokenised through this request. Do not use spaces. Never store these details.
CVN string Required
The customer verification code, this is referred to as a CVN, CVC, and sometimes CVV. This should never be stored.
ExpiryMonth number Required
The cards expiry date month. Must be a whole value in the range of 1-12.
ExpiryYear number Required
The cards expiry date year. Must be a whole value.
Customer dictionary Required
Code string Required Unique internal identifier assigned to the customer by Pay Advantage. This cannot be changed. Used to identify the customer this direct debit request will be sent to.

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/payment_authorizations_post-1

This method is used for attempting to charge a previously stored card and gets the response immediately. You will have to tokenise a card before it can be charged. This is so that we can ensure the best possible security is being used to protect both you and your customers data.

A successful response (STATUS 201) does not indicate that a payment was successful, it just means that charge was attempted. To determine a payments outcome you will need to check the ChargeStatus and Payment details in the response body for either "approved", "declined", or "undetermined". In the rare case that an "undetermined" response is received there is no other option other than re-querying this charge until its status has been resolved through the credit card network and a definitive ChargeStatus has been applied. We recommend re-querying every 15 minutes and no faster than once per 5 minute window. Do not attempt to re-charge this card until a definitive response has been received.

If the payment isn't successful or the charge declines you will be returned a fail code and reason in the response body under the Payment parameter. These are explained in more detail in our Enum Values & Fail Codes section here.

Below is an example of how to attempt to charge a card. The tokenised code is used in the request method and the body contains details of the payment. You can use ExternalID to attach a value from your system to the charge attempt. This can then be used when searching for charge attempts later on.

Example Request

curl -L -X POST 'https://api.payadvantage.com.au/v3/credit_cards/{code}/charges' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 -d '{
       "Amount": 123.45,
       "Description": "INV001",
       "OnchargeFees": true,
       "ExternalID": "Your system ID",
       "ReceiptEmail": "default"
     }'

Example Responses

STATUS 201 // Successful
    
{
	"ChargeStatus": "declined",
	"Description": "INV001",
	"ExternalID": "Your system ID",
	"CreditCard": {
		"Code": "CC1234",
		"IsActive": true
	},
  "Payment": {
		"Code": "ABC123",
		"Amount": 123.45,
		"AmountIncFees": 126.80,
		"FailReason": "Insufficient funds to process the requested amount",
		"FailCode": "insufficient_funds",
		"DateClears": null
	}
}

STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message."
	]
}

Request Parameters

Amount number Required
The payment amount to be charged from the tokenised card. Enter value as a currency amount in AUD e.g. 15.50
Description string Required
A description appended to a credit card charge to let you or your customer know what the payment was for. Write something that tells both the customer and the merchant what this payment is for e.g. "INV001 Payment".
OnchargeFees bool Required
Set wether you want to on charge the merchant service fee for this payment. If set to true the fee will be on charged to the customer. If set to false the fee will be paid by you based on your fee payment settings.
ExternalID string min = 1, max = 50
Identifier from an external system that can be appended to a credit card charge request.
ReceiptEmail string ListRequired
Choose wether you want to send an email to the customer on payment receipt or not. Setting this field as default will use the settings appended to the customer this card is related to. Valid Field Strings: default force_do_not_send force_send

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/credit_cards_get-1

Returns a tokenised credit cards details using the Code value of a card as an identifier. This is a useful method to retrieve hashed details that can be displayed to a customer to confirm this is the correct payment account.

Example Request

curl -L -X GET 'https://api.payadvantage.com.au/v3/credit_cards/{code}' \
 -H 'Authorization: Bearer {access_token}' \

Example Responses

STATUS 200 // Successful
    
{
	"Code": "CC1234",
	"CardHolder": "Bob Smith",
	"Expiry": "09/2022",
	"DisplayHash": "XXXX-XXXX-XXXX-1111",
	"CardType": "visa",
	"IsActive": true
}

STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message." 
	]
}

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/credit_card_charges_get-1

Returns a list of charges against a tokenised card arranged by date paid (most recent first by default). The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list.

Example Request

curl -L -X GET 'https://api.payadvantage.com.au/v3/credit_cards/{code}/charges' \
 -H 'Authorization: Bearer {access_token}' \

Example Responses

STATUS 200 // Successful
    
{
	"Records": [
		{
			"ChargeStatus": "approved",
			"Description": "INV001",
			"ExternalID": "Your External System Identifier",
			"CreditCard": {
				"Code": "CC123",
				"IsActive": true
			},
			"Payment": {
				"Code": "19EEFF",
				"Amount": 1234.56,
				"AmountIncFees": 1234.56,
				"FailReason": null,
				"FailCode": null,
				"DateClears": "2020-06-17T00:00:00",
				"DatePaid": "2020-06-12T13:08:58.273",
				"DateSettled": null,
				"PaymentType": "realtime_credit_card",
				"SettlementCode": null
			}
		},
		{
			...
		}
	]
	"Meta": {
		"page": 0,
		"recs_per_page": 15,
		"total_recs": 75
	}
}

STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [
		"Error message."
	]
}

Query Parameters

Parameters used in the request URL to return filtered or sorted data in the response body. These parameters follow the same rules as any standard HTML query string parameter. The first parameter is separated by ‘?’ and subsequent parameters are separated by ‘&’.

page integer
The page number you want to view using the zero-based index i.e. page=0 will return page 1 of Credit Card Charges. If the page index is greater than the last page, you will be returned an empty page. Negative indexes will return an error. This parameter is only used when viewing all credit card charges or querying charges against a specified card.
per_page integer min = 0, max = 1000
Number of records to view per page. By default the value is 100. Values greater than the max value, or negative values will return an error.
description string
A description appended to a credit card charge to let you or your customer know what the payment was for. Write something that tells both the customer and the merchant what this payment is for e.g. "INV001 Payment".
externalid string min = 1, max = 50
Optional identifier from an external system that can be recorded as an attribute against a credit card charge. Returns any credit card charge with this ID. Multiple charges can use the same ID.
payment Dictionary
code string min = 6, max = 6 Unique internal identifier specific to a single payment. datepaid date string Search by date a payment was attempted. datepaidto string Returns credit card charge records that were created before or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. payment.datepaidto={ddMMyyyy} datepaidfrom string Returns credit card charge records that were created after or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. payment.datepaidfrom={ddMMyyyy}

This documentation is deprecated

Please refer to the updated documentation https://docs.payadvantage.com.au/reference/credit_card_charges_get_by_external_id-1

Returns a list of charges against based on and external identifier by date paid (most recent first by default). The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list.

Please note that we do not prevent duplicate ExternalID entries so you will receive an array of charges for an ExternalID, even though there will typically only be one.

You can obviously use this ID for your own grouping purposes, however take care as this will make it difficult to verify that a charge was received by the Pay Advantage API if needed (e.g. an issue receiving or processing a response for a charge if a connectivity issue or 500 errors occur).

Example Request

curl -L -X GET 'https://api.payadvantage.com.au/v3/credit_cards_charges/{externalid}' \
 -H 'Authorization: Bearer {access_token}' \

Example Responses

STATUS 200 // Successful
    
{
	"Records": [
		{
			"ChargeStatus": "approved",
			"Description": "INV001",
			"ExternalID": "Your External System Identifier",
			"CreditCard": {
				"Code": "CC123",
				"IsActive": true
			},
			"Payment": {
				"Code": "19EEFF",
				"Amount": 1234.56,
				"AmountIncFees": 1234.56,
				"FailReason": null,
				"FailCode": null,
				"DateClears": "2020-06-17T00:00:00",
				"DatePaid": "2020-06-12T13:08:58.273",
				"DateCreated": "2020-06-12T13:08:58.273",
				"DateSettled": null,
				"PaymentType": "realtime_credit_card",
				"SettlementCode": null
			}
		},
		{
			...
		}
	]
	"Meta": {
		"page": 0,
		"recs_per_page": 15,
		"total_recs": 2
	}
}

STATUS 4## // Error
    
{
	"errorCode": "error_code",
	"messages": [ 
		"Error message." 
	]
}

Query Parameters

page integer
The page number you want to view using the zero-based index i.e. page=0 will return page 1 of Credit Card Charges. If the page index is greater than the last page, you will be returned an empty page. Negative indexes will return an error. This parameter is only used when viewing all credit card charges or querying charges against a specified card.
per_page integer min = 0, max = 1000
Number of records to view per page. By default the value is 100. Values greater than the max value, or negative values will return an error.
description string
A description appended to a credit card charge to let you or your customer know what the payment was for. Write something that tells both the customer and the merchant what this payment is for e.g. "INV001 Payment".
externalid string min = 1, max = 50
Optional identifier from an external system that can be recorded as an attribute against a credit card charge. Returns any credit card charge with this ID. Multiple charges can use the same ID.
payment Dictionary
code string min = 6, max = 6 Unique internal identifier specific to a single payment. datepaid date string Search by date a payment was attempted. datepaidto string Returns credit card charge records that were created before or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. payment.datepaidto={ddMMyyyy} datepaidfrom string Returns credit card charge records that were created after or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. payment.datepaidfrom={ddMMyyyy}

Articles in this section

Comments

Articles in this section

Related articles