Integration Guide

This guide walks you through implementing a real-time spend management experience using Astrada's APIs and webhooks; from onboarding a corporate to handling card lifecycle events.

For detailed endpoint specs, see the API Reference.

Business Actions → Technical Implementation

Suggested Webhook Subscriptions:

• cardsubscription.created
• cardsubscription.updated
• transaction.created
• transaction.updated

Suggested API Calls:

• POST /subaccounts
• PATCH /cardsubscriptions

Step 1: Corporate Is Onboarded

Create a Subaccount to segregate corporate client data. This represents a tenant boundary for card and transaction data.

Webhook: None required
API Call: POST /subaccounts
Associated Resource: Subaccount

Sample Request:

curl --request POST \
     --url https://api.astrada.co/subaccounts \
     --header 'accept: application/hal+json' \
     --header 'content-type: application/json' \
     --data '{
       "name": "Subaccount A",
       "configurations": {
         "VISA": { "countries": ["USA", "CAN"] },
         "MASTERCARD": { "countries": ["USA"] }
       }
     }'

Sample Response

{
  "_links": {
    "self": {
      "href": "/subaccounts/81e7c267-0927-4234-a2bd-78cef799de54"
    }
  },
  "accountId": "073fe1bb-3350-46ad-b3a6-32afb3780994",
  "id": "81e7c267-0927-4234-a2bd-78cef799de54",
  "name": "Subaccount A",
  "createdAt": "2024-05-01T17:08:43.810Z",
  "updatedAt": "2024-05-01T17:08:43.810Z",
  "configurations": {
    "VISA": { "countries": ["USA", "CAN"] },
    "MASTERCARD": { "countries": ["USA"] }
  }
}

Step 2: Card Is Enrolled

Card enrollment is typically handled via Astrada’s Cardholder Individual Enrollment SDK or asynchronously via Network Bulk Enrollment. No API calls are required from your side.

A CardSubscription is automatically created when a card is successfully enrolled.

Suggested Webhook: cardsubscription.created (monitor new card subscriptions)
Suggested API Calls: None
Associated Resources: Card, CardSubscription

Sample CardSubscription Payload

{
  "_links": {
    "self": {
      "href": "/card-subscriptions/75ea3c99-6bf5-4b16-8f68-0cdc43d75806"
    },
    "card": {
      "href": "/cards/5dec2c49-0aa5-4683-a317-427eb5d115f3"
    }
  },
  "id": "75ea3c99-6bf5-4b16-8f68-0cdc43d75806",
  "subaccountId": "f297d659-c13d-4219-aeaa-e10a845140a5",
  "cardId": "5dec2c49-0aa5-4683-a317-427eb5d115f3",
  "customerReferenceId": "5dec2c49-0aa5-4683-a317-427eb5d115f3",
  "enrollmentType": "cardholder-single",
  "state": "active",
  "effectiveDate": "2024-12-20T14:45:00Z",
  "expirationDate": "2025-06-19T14:45:00Z",
  "createdAt": "2024-12-19T14:45:00Z",
  "updatedAt": "2024-12-19T14:45:00Z"
}

Step 3: An Expense Is Made

When a spender makes a purchase, it will typically emit an authorization, which Astrada will capture in milliseconds.

Suggested Webhook: transaction.created (capture transaction details, notify spenders, initiate expense creation)
Suggested API Calls: None
Associated Resources: Transaction, TransactionMessage

Sample Transaction Payload

{
  "_links": {
    "card": {
      "href": "/cards/4d1ff59f-4286-4209-9662-92e174193562"
    },
    "subaccount": {
      "href": "/subaccounts/c6d5e036-361e-4773-a514-b9496cf2d2b5"
    },
    "self": {
      "href": "/transactions/8697df0c-9011-47ca-a52b-8d2a7a4ad903"
    },
    "messages": [
      {
        "href": "/transaction-messages/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4"
      },
      {
        "href": "/transaction-messages/934f8701-53e3-4a2b-a000-6bb52195d2ea"
      }
    ]
  },
  "acceptor": {
    "city": "LONDON",
    "country": "GBR",
    "mcc": "5734",
    "state": "LND"
  },
  "cardId": "4d1ff59f-4286-4209-9662-92e174193562",
  "cardholderBillingCurrency": "GBP",
  "cardholderBillingHoldAmount": 0,
  "cardholderBillingSettledAmount": 0.81,
  "createdAt": "2024-05-01T06:41:43.810Z",
  "descriptor": "Uber",
  "id": "8697df0c-9011-47ca-a52b-8d2a7a4ad903",
  "network": "MASTERCARD",
  "status": "SETTLED",
  "subaccountId": "c6d5e036-361e-4773-a514-b9496cf2d2b5",
  "transactionCurrency": "USD",
  "transactionHoldAmount": 0,
  "transactionOccurrenceDate": "2024-05-01",
  "transactionSettledAmount": 1,
  "updatedAt": "2024-05-02T08:41:43.810Z"
}

Augmenting transaction.created with a projection of TransactionMessage data

If you want TransactionMessage data included, you can augment transaction.created with a projection. Once enabled, an array containing all correlated messages will be included on the transaction aggregate payload inside the "_embedded" field. To enable the expanded payload, contact your Account Manager.

Sample Transaction Payload with TransactionMessage Projection

{
  "_embedded": {
    "messages": [
      {
        "_links": {
          "self": {
            "href": "/transaction-messages/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4"
          }
        },
        "approvalCode": "537254",
        "transactionReference": "IWVQ22_2024-04-24",
        "dateTime": "2024-04-24T13:39:45",
        "id": "f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4",
        "messageType": "FINL_ADVC",
        "network": "MASTERCARD",
        "result": "APPROVED"
      }
    ]
  }
}

Step 4: An Expense Record Is Updated

After the initial expense is made, additional payment events may occur (e.g., clearing, refund). Astrada updates the Transactionobject so that it incorporates all relevant payment events.

Suggested Webhook: transaction.updated (reflect current status or enrich downstream records)
Suggested API Calls: None
Associated Resources: Transaction, TransactionMessage

If you opt in to augment the transaction webhook events with TransactionMessage data, you should expect to receive it on both transaction webhooks (transaction.createdand transaction.updated).

Step 5: Card Is Deactivated

Card subscriptions may be updated to a terminal state when cards are disabled.

Suggested Webhook: cardsubscription.updated (detect deactivation)
Suggested API Call: PATCH /cardsubscriptions (only for individually enrolled cards)
Associated Resource: CardSubscription

Step 6: Card Is Re-Enrolled

When cards are re-enabled or reconnected, Astrada creates a new subscription automatically.

Suggested Webhook: cardsubscription.created (detect new subscriptions on top of an existing card)
Suggested API Calls: None
Associated Resource: CardSubscription

Final Notes

• Use webhooks to keep your platform reactive and event-driven.
• Use Transaction as your system of record.
• Use GET /transactions if you wish to present a list of transactions to a user.
• Use Transaction Messages for debugging or latency-sensitive use cases.
• Transaction Messages should have slightly lower latency than Transactions.
• Transaction Messages represent a singular event in a payment lifecycle and are useful for debugging or custom matching logic.

For more detail on transaction enrichments (e.g., tax, tip, etc.), contact your Account Manager or [email protected].