TABLE OF CONTENTS

DinoRawrs.com (Example)

DinoRawrs.com is a startup that helps restaurants. They want to provide a website where customers can view menus and place orders as well as a point of sale that allows the restaurant to accept credit cards with chip & pin.


DinoRawrs.com has chosen to use ACME as their payment platform so they can easily accept credit card payments, distribute those payments to the corresponding restaurants while keeping a nominal fee for themselves.  


Using ACME means that they can focus on their website and will not need to build a secure, cost-effective payment system that will:

  • Process payments and distribute the funds to each restaurant, keeping a tiny fee for DinoRawrs.

  • A transaction engine that provides reporting to the individual restaurants as well as DinoRawrs

  • Prevent credit card fraud

  • Optimize credit card processing fees


Accepting credit cards on your website (server to server)

ACME makes it easy to accept payments on your website with your frontend making a Javascript call to your backend with the credit card information. Your backend then makes a call to ACME to generate a single use token. Once the customer is ready to process the order then another call is made from your backend to make a charge against the token.  


Each call will contain a merchant id and your secret payment key. The merchant id will be placed in the URL and the payment key will be passed in as the header ‘x-acme-payment-key’. See below CURL examples.


Generating a single use token

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



Completing the sale and charging against the token

After the customer has filled their cart and confirmed the order it’s time to make a second call to charge their credit card. This is done by providing the previously obtained token and the amount you want to charge.  The customer clicks the Confirm button and your front end makes an AJAX call to your backend which in turn makes a call to ACME to process the charge. Here is a sample Sale call.


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


That’s it. Just two calls and DinoRawrs is accepting secure, cost-effective payments on their website and distributing the money to the restaurants. RAWR means I Love It in dinosaur!


The Point of Sale

DinoRawrs is also developing a restaurant centric point of sale. The point of sale will run on an android tablet and be web based but it will also accept chip & pin credit cards. This is done with ACME Javascript library. The library is downloaded with NPM. They then use the library to list the devices, select the device they want to communicate with and start accepting credit cards in a secure fashion. Connecting to the device only needs to be done once and after that the app will automatically connect to the device when the app is launched.


Cards on File

As a convenience many restaurants want to store the credit card so that the customer only has to enter it once. ACME makes storing and managing the card on file easy, cost-effective and secure. 


Storing the card on file is done with a single backend call very similar to generating a one time token. In addition you can provide your own customer id and payment method id and use your payment method id to complete the sale.


Creating a card on file

curl -X POST https://sandX-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 response from the card on file call will contain a token that can be used to complete the sale or you can complete the sale using the externalPaymentMethodId that you provided.


Completing a sale

Checking out using the externalPaymentMethodId

curl -X POST https://sandX-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 they are no longer using. Use the externalCustomerId you provided when creating the card on file to list the cards that a customer has on file.


Listing cards on file for customer C-8282

curl https://sandX-api.acmeticketing.net/v1/payment/[MerchantId]/customer/ext/c-8282/card -H 'x-acme-payment-key: [PaymentKey]'

This will return an array of cards on file for that customer.

Sample response of cards on file.

[
{
"card": {
"expirationDate": {
      "month": "07",
       "year": "2025"
},
  "brand": "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://sandX-api.acmeticketing.net/v1/payment/[MerchantId]/tokens/ext/[externalPaymentMethodId] -H 'x-acme-payment-key: [PaymentKey]'


Looking up a card on file by its token

curl https://sandX-api.acmeticketing.net/v1/payment/[MerchantId]/tokens/[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://sandX-api.acmeticketing.net/v1/payment/[MerchantId]/tokens/ext/[externalPaymentMethodId] -H 'x-acme-payment-key: [PaymentKey]' 


Deleting a card on file by its token

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



Reporting Dashboard

DinoRawrs wants to provide their restaurants with a dashboard to let them know what transactions have taken pace. 


It’s super easy to get a list of transactions that have taken place from ACME. Simply provide the start time and end time as ISO8601 strings and perform an HTTP Get


Example of getting all transactions for a restaurant for the month of December 2021 Pacific Time.

curl "https://sandX-api.acmeticketing.net/v1/payment/[MerchantId]/transaction?startTime=2021-12-01T00:00:00-0800&endTime=2021-12-31T23:59:59-0800" -H 'x-acme-payment-key: [PaymentKey]'