Credit Cards

Storing/Tokenising a Credit Card

Credit cards can be stored and used later in Debit Batches and individual charges. 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. When passed through during tokenisation we sometimes use the CVN to verify the card before discarding. 

POST: /credit_cards
{
	CardNumber : "4444333322221111",
	ExpiryMonth : 9,
	ExpiryYear : 2022,
	CardHolder : "Mr Test Card",
	CVN : "123",
	Customer : { Code: "ABC123" }
}

Response:

POST: /credit_cards
{
	Code : "CC1234",
	DisplayHash : "44###########111",
	CardHolder : "Mr Test Card",
	Expiry : "09/2022",
	Customer : { Code : "ABC123" }

}

 

Charging a stored Credit Card

This method is used for attempting to charge a previously stored card and get the response immediately.

You can use ExternaID to attach a value from your system to the charge attempt, this can then be used when searching for charge attempts later on.

POST: /credit_cards/{credit_card_code}/charges
{
	Amount : 123.45,
	Description : "Weekly Fee",
	OnchargeFees : true (default is false),
	ExternalID : “Your system ID”,
	CVN : null (set to null if card not present. NEVER STORE THIS!)
}

 

Successful Response:

{
    "Status": "succeeded",
    "Description": "Weekly Fee",
    "ExternalID": "Your system ID",
    "CreditCard": { "Code": "ABC123" },
    "Payment": {
        "Code": "DEFH32",
        "Amount": 1234.56,
        "AmountIncFees": 1236.21,
        "FailReason": null,
        "FailCode": null,
        "DateClears": "2017-06-09T00:00:00",
        "URI": "/v2/payments/DEFH32"
    },
    "Route": "credit_cards/{credit_card_code}/charges"
}

 

Unsuccessful Response:

{
    "Status": "failed",
    "Description": "Weekly Fee",
    "ExternalID": "Your system ID",
    "CreditCard": { "Code": "ABC123" },
    "Payment": {
        "Code": "DEFH32",
        "Amount": 1234.56,
        "AmountIncFees": 1236.21,
        "FailReason": "Insufficient funds to process the requested amount",
        "FailCode": "S",
        "DateClears": null,
        "URI": "/v2/payments/DEFH32"
    },
    "Route": "credit_cards/{credit_card_code}/charges"
}

 

Query charges for a stored card

We recommend managing payments through the payments controller, however if you require the facility to search for all charges against a tokenised card then you may use the following call:

GET: /credit_cards/{credit_card_code}/charges

Response: 

{
    "Records": [
        {
            "Status": "succeeded",
            "Description": "Upfront fee",
            "ExternalID": “Your system ID”,
            "CreditCard": {"Code": "ABC123"},
            "Payment": {
                "Code": "19EEFF",
                "Amount": 1234.56,
                "AmountIncFees": 1234.56,
                "FailReason": null,
                "FailCode": null,
                "DateClears": "2017-06-17T00:00:00",
                "DatePaid": "2017-06-12T13:08:58.273",
                "DateSettled": null,
                "SettlementCode": null,
                "URI": "/payments/19EEFF"				
            }
        },
        {
            "Status": "succeeded",
            "Description": "Weekly Fee",
            "ExternalID": null,
            "CreditCard": {"Code": "ABC123"},
            "Payment": {
                "Code": "19FFGG",
                "Amount": 99.00,
                "AmountIncFees": 101.99,
                "FailReason": null,
                "FailCode": null,
                "DateClears": "2017-06-17T00:00:00",
                "DatePaid": "2017-06-12T12:05:03.47",
                "DateSettled": null,
                "SettlementCode": null,
                "URI": "/payments/19FFGG"				
            }
        }],
    "Meta": { “page”: 0, “recs_per_page”: 100, “total_recs”: 2 }
}

 

Query charges for an External Identifier (ExternalID)

If you require the facility to search for a charge matching an identifier specified when creating the charge you can do so using the get request detailed below. 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).

GET: /credit_cards/charges/{externalid}

Response: 

{
    "Records": [
        {
            "Status": "succeeded",
            "Description": "Upfront fee",
            "ExternalID": “Your system ID”,
            "CreditCard": {"Code": "ABC123"},
            "Payment": {
                "Code": "19EEFF",
                "Amount": 1234.56,
                "AmountIncFees": 1234.56,
                "FailReason": null,
                "FailCode": null,
                "DateClears": "2017-06-17T00:00:00",
                "DatePaid": "2017-06-12T13:08:58.273",
                "DateSettled": null,
                "SettlementCode": null,
                "URI": "/payments/19EEFF"				
            }
        }],
    "Meta": { “page”: 0, “recs_per_page”: 100, “total_recs”: 1 }
}

 

Have more questions? Submit a request

Comments