Sandbox Test Case: Demonstrate Idempotency Key

Last updated: October 6, 2026

Demonstrate Idempotency Key

Utilizing an Idempotency-Key header for routine creation will protect your program from inadvertent creation of duplicate routines.

Reference: Recommendations for a robust integration: Routine creation

Environment

Sandbox

Required deliverables

Request-Id(s), Idempotency-Key value
Submit all deliverables directly in the checklist, in the Idempotency Key row.

Steps

1. Generate an Idempotency-Key

Generate a unique value in UUID v4 format. Reuse it for both requests.

Note that the Idempotency-Key value that you use does not have an expiration.

2. Submit the first routine request

Send a routine creation request to sandbox with the Idempotency-Key header set.

curl -X POST https://api-sandbox.astra.finance/v1/routines \
  -H "Authorization: Bearer {user_access_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid_1}" \
  -d '{
    "name": "Idempotency test",
    "type": "one-time",
    "payment_type": "debit",
    "source_id": "{source_card_id}",
    "destination_id": "{destination_card_id}",
    "amount": 10.00
  }'

Please note: this is just a sample routine request. Submit a routine that matches your approved use case(s).

3. Record the response

Note the routine_id and the Request-Id.

4. Submit the identical request again

Same payload, same Idempotency-Key value. Do not generate a new key.

5. Confirm the same routine_id is returned

Example: Creating a routine with Idempotency-Key: uuid_1 and a request payload of payload_1, results in routine_1. If you submit another routine request with Idempotency-Key: uuid_1 and a request payload of payload_1, the resulting response will contain details of routine_1 as well.

It is the Idempotency-Key and unique payload pair that is utilized for idempotency.

If for example routine creation requests were submitted like so, the following outcomes would take place:

  1. Routine request 1

    1. Idempotency-Key: uuid_1

    2. Payload: payload_1

    3. Resulting routine: routine_1

  2. Routine request 2

    1. Idempotency-Key: uuid_1

    2. Payload: payload_2

    3. Resulting routine: routine_2

  3. Routine request 3

    1. Idempotency-Key: uuid_2

    2. Payload: payload_1

    3. Resulting routine: routine_3

6. Submit your notes

Please leave in your notes which environment the routines were created against (sandbox).

Checklist

Environment (sandbox)

Idempotency-Key value

Request-Id, first request

Request-Id, second request

routine_id returned (both requests)

Good to know

Handling 502, 504 and 5XX responses

Occasionally, you may receive a 502 , 504 , or 5XX response to your routine creation request. This does not necessarily mean the routine failed to create, and you could potentially receive a routine_updated webhook.

Do not treat a 502 , 504 , or 5XX response as an outright failure, instead:

  • Submit all unique routine requests with an Idempotency-Key header

  • In the event the first attempt receives a 502 , 504 , or 5XX response:

    • You may receive routine_updated webhooks for the routine_id generated from the initial request that received a 502 , 504 , or 5XX response

      • There is no guaranteed timing on when you might receive this routine_updated webhook, but it will typically be sent within minutes of the initial request.

    • You are safe to retry the request with the same payload and same Idempotency-Key header value (only one routine will be created from the two requests)

Implementation Recommendations

  1. Submit all routine creation requests with an Idempotency-Key header.

    1. A unique routine request is one that has the same Idempotency-Key header value and same payload.

  2. If a timeout or 5XX response is received

    1. Your system may receive a routine_updated webhook. You should account for your system receiving a webhook for an unknown routine_id at any time.

      1. Correlate the unknown routine_id by fetching routine details and matching those against the request.

    2. Retry the routine creation request with the same Idempotency-Key header value and payload with exponential backoff and a maximum number of retries.