ACME Payments documentation is a draft & work in progress.  Updates may be published periodically.  



TABLE OF CONTENTS


Browser or Server Side Token call



Depending on your integration type as it related to PCI considerations, you will either want to get a card token from the browser so that your servers never see the light of a card PAN (Personal Account Number) or get a card token from the server if you accept having your servers see PAN.


In the event you decide on a browser-originated integration to get the token, during the platform onboarding process, we will give you a publishable key to be passed as an HTTP request header into the get token API. Additionally, during the onboarding, we will white list those calls to only be allowed from your top-level domain and subdomains, by taking advantage of the browser cross-origin (CORS) domain permissions. See another example of a CORS acme API here.

x-acme-payment-key


In the event of opting for a server to server call, then , as any such call, you will use the platform private API key supplied during the platform onboarding.


Generate a Single Use Token

Generate a token that can be use one time.

POST v1/payment/{mid}/tokens/singleuse

 

Request Parameters

The merchant id (mid) of the seller that a token is being generated for.

Request Body

A Token object containing the credit card information you want the token for.  No customer information should be provided as this is generating a single use token and not a payment method or card on file.


Sample Request

POST https://sandX-api.acmeticketing.net/v2/payment/987-654-321/tokens/singleuse


Response

A Token object that can be used a single time.



Generate a Multi Use Token

Generate a token for a card on file.  This token can be used multiple times in the future but only can be used for the current tenant.


POST v1/payment/{mid}/tokens/multiuse

 

Request Parameters

The merchant id of the seller that a token is being generated for.

Request Body

A Token object containing the credit card information you want the reusable token for and an external customer id that you can use to reference the reusable token in the future.  You can retrieve the token in the future using the external id you provide.  If an external customer ID is not initially provided, you will need to store the id from the response in order to access the token by customer ID in the future.


Sample Request

POST https://sandX-api.acmeticketing.net/v2/payment/987-654-321/token/multiuse


Response

A Token object representing a card on file that can be used in the future.  It can only be used for sale transactions to the current tenant.


Retrieve a Token by External Customer ID

Retrieve a list of reusable tokens by the external customer id that you provided, or we returned when creating the multi use token.

GET v1/payment/{mid}/customer/{customerId}/tokens

Request Parameters

The merchant id of the seller.

The external customerID in the URL of the request. The external customer ID was submitted during the multi-use token generation process.


Sample Request

GET https://sandX-api.acmeticketing.net/v2/payment/987-654-321/customer/abc98765/tokens


Response

A list of Token objects



Retrieve a Token by Token ID

GET v1/payment/{mid}/tokens/{token}

Request Parameters

The merchant id (mid) of the seller.

The token that you want to retrieve in the URL of the request. 


Sample Request

GET https://sandX-api.acmeticketing.net/v2/payment/987-654-321/tokens/123-456-789


Response

The corresponding Token object.



Delete a Token

Delete the specified token

DELETE v1/payment/{mid}/tokens/{token}


Request Parameters

The merchant id (mid) of the seller

The token that you want to delete in the URL of the request. 


Sample Request

DELETE https://sandX-api.acmeticketing.net/v2/payment/987-654-321/tokens/123-456-789


Returns

Returns the deleted Token object.


Updating a Token

PUT v1/payment/{mid}/tokens

Request Parameters

The merchant id (mid) of the seller that the token being updated belongs to.

Request Body

The entire token as you would like it to be updated.  The id of the token is required in the body.  You will only be able to update the expiration date of the card.


Sample Request

PUT https://sandX-api.acmeticketing.net/v2/payment/987-654-321/tokens


Returns

Returns the resulting Token object.



Token Object

NameTypeDescriptionRequired
idnumberA unique id for this tokenRead Only
tokenstringA unique token used to make the sale
Read Only
typestringThe type of token it is ‘single’ or ‘multiple’. Read Only
paymentMethodstringThe type of payment method.  Currently we only support ‘creditCard’, future might include values like ‘ach'Required
cardobject (see below)The card information. Used to create the payment method during token generation. Responses containing the payment method will not contain the card pan. Required


Card Object

NameTypeDescriptionRequired
panstringThe credit card numberRequired
lastFourstringLast four digits of the credit card on fileRead Only
expirationDateobjectExpiration date of the credit card on fileRequired
expirationDate.monthstring
Required
expirationDate.yearstring
Required
cvcstring
The cvc of the card
Required
postalCodestringThe zip code for the billing address of the card. When passed it will be passed through. Error will be returned during the sale transaction call if postal code does not match the cards bOptional
brandstringBrand of the credit card on fileRead Only


Sample Request Body


This is a single representation of the TokenRequest object.  It will be used in the request bodies.  Please review individual API documentation for specific details.

{
  "paymentMethod": "creditCard",
  "card": {
    "pan" : "4242424242424242",
    "expirationDate" : {
      "month" : "8",
      "year" : "2023"
    },
    "cvc" :  "123",
    "postalCode": "12345"
  }
}



Sample Response Body


This is a single representation of the TokenResponse object.  Please review individual API documentation for specific details.


{
  "id" : 692,
  "token" : "828433fa-6833-43bf-9856-a5d6c2144742",
  "type" : "single",
  "paymentMethod": "CreditCard",
  "card" : {
    "lastFour" : "1234",
    "expirationDate": {
       "month" : "08",
       "year": "2023"
    },
    "cvc" :  "123",
    "postalCode": "12345",
    "brand": "Visa"
  }
}