Getting Started

The fastest path from zero to your first transaction, and a map of how each business event becomes an API call and a webhook. Every step links out to the guide with the detail.

How enrollment works, in one picture

However a card is enrolled, it becomes the same thing: a durable cardId, a card subscription announced by cardsubscription.created, and transactions that carry that cardId. You enroll over one of three rails (card number, bank connection, or network bulk feed), and the subscription's enrollmentType records which one. A single set of handlers covers all three, so read enrollmentType as a label, never a branch. The full model is Unified Card & Bank Feeds.

Business events → what to implement

Steps

1. Get your account

Contact your Astrada representative. You'll receive API credentials (server-to-server, OAuth 2.0 client-credentials), SDK credentials (if you enroll cards client-side), your account ID, and a Postman collection. For the token mechanics, see Authentication.

2. Create a subaccount

Cards and transactions are segmented under a subaccount, which is also where enrollment controls and verification policy apply.

POST /subaccounts HTTP/1.1
Content-Type: application/json

{
  "name": "Acme Corp",
  "configurations": { "VISA": { "countries": "*" }, "MASTERCARD": { "countries": "*" } }
}

curl -X POST https://api.astrada.co/subaccounts \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp", "configurations": { "VISA": { "countries": "*" }, "MASTERCARD": { "countries": "*" } } }'

{
  "name": "Acme Corp",
  "configurations": { "VISA": { "countries": "*" }, "MASTERCARD": { "countries": "*" } }
}

configurations sets, per network, which card-issuing countries are eligible. "*" inherits your account's own capabilities and is the safer default. For the full rules, see Account & Subaccount Configuration.

3. Register a webhook

Nothing reaches you until you register an endpoint for the event types you want:

POST /webhooks HTTP/1.1
Content-Type: application/json

{
  "url": "https://example-api.com/webhooks",
  "eventTypes": ["transactionmessage.created", "transaction.created", "transaction.updated"],
  "subaccountId": "<SUBACCOUNT_ID>"
}

{
  "url": "https://example-api.com/webhooks",
  "eventTypes": ["transactionmessage.created", "transaction.created", "transaction.updated"],
  "subaccountId": "<SUBACCOUNT_ID>"
}

The response's secret is returned once, at creation, so save it for signature verification. See Webhooks for retries and the (required) signature-verification step.

4. Connect a bank (optional)

Connecting a bank adds bank-only transactions (fees, transfers, payroll), earlier settlement for card spend, and American Express enrollment over the bank rail. It is independent of card enrollment, so connect it early: every card enrolled afterward then benefits from its first transaction, because auto-detected card-to-account links do not backfill history. Remember to add banklink.completed to the eventTypes from Step 3. For the full walkthrough, see Quick Start: Bank Linking.

5. Enroll a card

Enroll over the rail that fits your product:

• Unified Enrollment SDK: one embedded flow that routes card, bank, and bulk automatically.
• Quick Start: Card Enrollment: the Card Enrollment SDK, with hosted 3DS UI for card-number enrollment.
• Direct API Card Enrollment: server-to-server, no SDK.

On success, cardsubscription.created fires. Re-enrolling reuses the same cardId and creates a new subscriptionId.

6. Receive transactions

Card and bank activity arrives as transaction.created / transaction.updated, each carrying the cardId you match against your records. _links.messages points to the underlying Transaction Messages. If you derive amounts from individual messages, exclude the ids in supersededMessageIds (duplicate clearings), or just use the transaction's own settled amounts. For every event and payload, see Event Types.

7. Manage and query

• Deactivate a subscription: PATCH /card-subscriptions/{id} with { "state": "deactivated" }. This is final, and not available for bulk-enrolled subscriptions.
• Fetch transaction state: GET /transactions/{id}, or list with GET /transactions.

Next steps

• Unified Card & Bank Feeds: the shared model across every rail.
• Quick Start: Bank Linking and Quick Start: Card Enrollment.
• Event Types: every webhook payload, in one place.