In this quickstart you will walk through acquiring an Apple Pay token, creating a Circle payment token, and making a payment.

1. Get an API key

The Circle Payments API uses API keys as the mechanism to authenticate client requests. The API key must be set in the Authorization header of the request sent from your backend server. The format of the header is Bearer secret-key-value.

Learn more about authenticating API calls here.

To obtain an API key for the sandbox environment, simply create an account and generate a new key in settings - it only takes a few seconds.

Get an API key

Once you have generated your API key, record it in a secure place.

2. Acquire Apple Pay Token Data

For the quickstart we recommend acquiring the Apple Pay token from our sample app that provides a simple way to generate a token without any setup. To acquire an Apple Pay token from Apple please see Apple Pay Setup section.

3. Create Payment Token

Once you have acquired the Apple Pay token data you can then create a one time use payment token by creating a payment token POST: /v1/paymentToken.

# Replace ${YOUR_API_KEY} with the API key obtained on step 1
curl --location --request POST 'POST https://api-sandbox.circle.com/v1/paymentToken' \
--header 'X-Request-Id: 79d2bf8a-b301-43d6-a3fb-d2cd0f81e465' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "type": "applepay",
    "tokenData": {
        "version": "EC_v1",
        "data": "t7GeajLB9skXB6QSWfEpPA4WPhDqB7ekdd+...T6Ms7PhiNZpuGEE2QE=",
        "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQEx.../WIDkHWiFuSm5a3NVox7DlyIf0AAAAAAAA=",
        "header": {
            "ephemeralPublicKey": "MFkwEwYHKoZIzj.../zlsw==",
            "publicKeyHash": "tqYV+tmG9aMh+l/K6cicUnPqkb1gUiLjSTM9gEz6Nl0=",
            "transactionId": "3cee89679130a4b2617c76118a1c62fd400cd45b49dc0916d5b951b560cd17b4"
        }
    }'

{  
 "data": {  
   "id": "gc988ed5-c189-4f70-a074-e5beb7eb8e32",  
   "type": "applepay",  
   "expiresOn": "2022-01-18T19:20:00Z",  
   "cardDetails": {  
     "expMonth": 1,  
     "expYear": 2020,  
     "network": "VISA",  
     "last4": "0123",  
     "bin": "401230",  
     "fundingType": "credit",  
     "issuerCountry": "US"  
   },  
   "createDate": "2020-04-10T02:13:30.000Z",  
   "updateDate": "2020-04-10T02:13:30.000Z"  
 }  
}

4. Create Payment

Create a payment with the payment token ID acquired in the response from step 3.

# Replace ${YOUR_API_KEY} with the API key obtained on step 1
curl --location --request POST 'POST https://api-sandbox.circle.com/v1/payment' \
--header 'X-Request-Id: 51308791-f550-4381-a083-312282fc68a5' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
    "metadata": {
        "email": "[email protected]",
        "sessionId": "DE6FA86F60BB47B379307F851E238617",
        "ipAddress": "244.28.239.130"
    },
    "amount": {
        "amount": "3.14",
        "currency": "USD"
    },
    "autoCapture": true,
    "verification": "none",
    "source": {
        "id": "gc988ed5-c189-4f70-a074-e5beb7eb8e32",
        "type": "paymenttoken"
    },
    "description": "Payment"
}'

{  
 "data": {  
   "id": "e6b8d255-e909-4e0f-ae58-aece722bf9fe",  
   "type": "payment",  
   "merchantId": "b42af422-702d-4787-90c8-f4a84440ec53",  
   "merchantWalletId": "0123456789",  
   "source": {  
     "id": "gc988ed5-c189-4f70-a074-e5beb7eb8e32",  
     "type": "paymenttoken"  
   },  
   "description": "Payment",  
   "amount": {  
     "amount": "3.14",  
     "currency": "USD"  
   },  
   "status": "pending",  
   "captured": false,  
   "refunds": [],  
   "createDate": "2022-03-10T14:10:47.665Z",  
   "updateDate": "2022-03-10T14:10:47.900864Z"  
 }  
}

5. Check the status of your Apple payment

Now make an API call to retrieve the status of your card payment using the get payment endpoint. Use your API key from step 1 and the payment identifier you obtained on step 3.

# Replace ${YOUR_API_KEY} with the API key obtained on step 1
# Replace ${PAYMENT_ID} with the payment id obtained on step 4
curl -H 'Accept: application/json' \
--header 'X-Request-Id: 79d2bf8a-b301-43d6-a3fb-d2cd0f81e465' \
--header 'Authorization: Bearer ${YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
  -X GET --url https://api-sandbox.circle.com/v1/payments/${PAYMENT_ID}

You should receive a response such as below.

{  
 "data": {  
   "id": "e6b8d255-e909-4e0f-ae58-aece722bf9fe",  
   "type": "payment",  
   "merchantId": "b42af422-702d-4787-90c8-f4a84440ec53",  
   "merchantWalletId": "0123456789",  
   "source": {  
     "id": "gc988ed5-c189-4f70-a074-e5beb7eb8e32",  
     "type": "paymenttoken"  
   },  
   "description": "Payment",  
   "amount": {  
     "amount": "3.14",  
     "currency": "USD"  
   },  
   "status": "confirmed",  
   "captured": false,  
   "refunds": [],  
   "createDate": "2022-03-10T14:10:47.665Z",  
   "updateDate": "2022-03-10T14:10:47.900864Z"  
 }  
}

🎉 You are all done!

Your payment will eventually change its status from confirmed to paid - at that point you have funds in your account available for use.

5. Like what you see? Keep going!

By accepting a card payment that settles in USDC, you have just touched the tip of the iceberg of Circle APIs.

Make sure you read the longer form guide on accepting payments online. Check how to subscribe to notifications on changes in payments status. Also make sure you check the rest of the documentation - a few starting points are suggested below.

6. Ready for the next step?

If you are in advanced stages of experimenting with our APIs and want to plan moving to production, please start by applying for a Circle Account and subsequently reach out to sales. We'll be happy to walk you through to the next steps.

We can't wait to see what you are going to build!