Overview

ACME gives you an easy way to provide the convenience of storing the card on file for the customer.  That way the customer only needs to enter their credit card information once.  This document will explain using ACME to create and manage card on file.

ACME also provides you the ability to pass in your customer id and payment method id and reference these when charging against a card on file and managing the customer's cards on file.  You can provide an externalCustomerId to group payment methods with your customer id and an externalPaymentMethodId to make a sale.


Creating a card on file

Creating a card on file is done by making an HTTP POST request to /v1/payment/[MerchantId]/tokens/card with your PaymentKey as the 'x-acme-payment-key' header and the request body containing the credit card information. This request will need to come from your backend server as it contains your PaymentKey which must be protected.


example of creating a card on file

curl -X POST https://sand8-api.acmeticketing.net/v1/payment/[MerchantId]/tokens/card -H 'Content-Type: application/json' -H 'x-acme-payment-key: [PaymentKey]' -d '{
  
"paymentMethod" : "creditCard",
  
"externalCustomerId" : "C-8282",
  
"externalPaymentMethodId" : "CC-9393",
  
"card" : {
    
"pan""4242424242424242",
    
"cvc""123",
    
"expirationDate" : {
       
"month""07",
       
"year""2025"
}
} }


The body of the request is a Token Object and the response is a Token Response Object.  Please see the Payment: Token page for more information.


Making a sale 

Making a sale with a card on file is done by providing the amount for the sale and either the token of the card on file or the externalPaymentMethodId that you provided.


Example making a sale with the token

curl -X POST https://sand8-api.acmeticketing.net/v1/payment/[MerchantId]/sale -H 'Content-Type: application/json' -H 'x-acme-payment-key: [PaymentKey]' -d '{
  "token" : "1234-5678-90AB",
"charge" : {
"amount" : 10.0
} }' 



Example making a sale with an externalPaymentMethodId

curl -X POST https://sand8-api.acmeticketing.net/v1/payment/[MerchantId]/sale -H 'Content-Type: application/json' -H 'x-acme-payment-key: [PaymentKey]' -d '{
"externalPaymentMethodId" : "CC-9393",
"charge" : {
"amount" : 10.0
} }' 



Managing cards on file

Sometimes customers might want to see which cards you have on file for them and remove cards that are no longer valid. Use the externalCustomerId you provided when creating the card on file to list the cards that a customer has on file.


Getting a list of cards on file for a customer is done by making an HTTP GET request to the endpoint /v1/payment/[MerchantId]/customer/[ExternalCustomerId]/card .  This will return an array of the cards for that customer.


Example array of cards on file for a customer

[
    {
        "card": {
            "expirationDate": {
                "month": 
"07",
                "year": 
"2025"
            },
            "firstName": 
"Visa",
            "lastFour": 
"4242"
        },
        "externalCustomerId": 
"C-8282",
        "externalPaymentMethodId": 
"CC-8282",
        "paymentMethod": 
"CreditCard",
        "token": 
"463c508g-d6df-2828-6cd4-9e32e3f746be",
        "type": 
"multiple"
    }
]


You can also look up an individual card on file using either the token for the payment method or the externalPaymentMethodId that you provided


Looking up a card on file using the externalPaymentMethodId you provided

curl https://sand8-api.acmeticketing.net/v1/payment/[MerchantId]/card/ext/[externalPaymentMethodId] -H 'x-acme-payment-key: [PaymentKey]'


Looking up a card on file by its token

curl https://sand8-api.acmeticketing.net/v1/payment/[MerchantId]/card/[Token] -H 'x-acme-payment-key: [PaymentKey]' 


Deleting a card on file can also be done either by the token or the externalPaymentMethodId that you provided. 

Deleting a card on file using the externalPaymentMethodId that you provided.

curl -X DELETE https://sand8-api.acmeticketing.net/v1/payment/[MerchantId]/card/ext/[externalPaymentMethodId] -H 'x-acme-payment-key: [PaymentKey]' 


Deleting a card on file by its token

curl -X DELETE https://sand8-api.acmeticketing.net/v1/payment/[MerchantId]/card/[Token] -H 'x-acme-payment-key: [PaymentKey]'