Setup

Agentic Payments enrolls only cards that support Cloud Token Framework and Visa Token Service tokenization. Check with your card issuer or BIN sponsor before you create an enrollment. The Visa fact sheet covers what the framework provides.

Before you start

A Reap API key for the sandbox or production environment
Agentic Payments enabled on your project
An HTTPS return URL that receives the user after the hosted card entry page and the hosted approval page

Every request takes an Authorization header and a Reap-Version header. The examples below use the sandbox host. Switch to the production host when you go live.

Store a card

Create the enrollment

Pick the source that matches the card you are storing. POST /agentic/enrollments requires an Idempotency-Key. A retry with the same key replays the first response instead of storing the card twice.

Reap card
BIN sponsor card
External card

Use this source for a card Reap already issued.

Request

curl --request POST \
  --url https://sandbox.api.reap.global/agentic/enrollments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Reap-Version: <reap-version>' \
  --data '{
    "source": "REAP_CARD",
    "cardId": "<card-id>"
  }'

Response

{
  "id": "<enrollment-id>",
  "status": "REQUIRES_ACTION",
  "source": "REAP_CARD",
  "owner": {
    "type": "REAP_USER",
    "id": "<user-id>"
  }
}

The owner block names the cardholder that Reap resolved from the card.

Use this source for a card issued by a BIN sponsor.

Request

curl --request POST \
  --url https://sandbox.api.reap.global/agentic/enrollments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Reap-Version: <reap-version>' \
  --data '{
    "source": "BIN_SPONSOR",
    "cardId": "<card-id>"
  }'

Response

{
  "id": "<enrollment-id>",
  "status": "REQUIRES_ACTION",
  "source": "BIN_SPONSOR"
}

This response carries no owner block. The sponsor card ID already resolves the cardholder on the sponsor side.

Use this source when the user enters a new card. Send the owner reference from your own system and the URL the user returns to.

Request

curl --request POST \
  --url https://sandbox.api.reap.global/agentic/enrollments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Reap-Version: <reap-version>' \
  --data '{
    "source": "EXTERNAL",
    "owner": {
      "type": "CLIENT_REFERENCE",
      "id": "<your-customer-id>",
      "email": "jsmith@example.com"
    },
    "presentation": {
      "type": "REDIRECT",
      "returnUrl": "https://example.com/cards/added"
    }
  }'

Response

{
  "id": "<enrollment-id>",
  "status": "REQUIRES_ACTION",
  "source": "EXTERNAL",
  "owner": {
    "type": "CLIENT_REFERENCE",
    "id": "<your-customer-id>",
    "email": "jsmith@example.com"
  },
  "nextAction": {
    "type": "REDIRECT",
    "url": "<hosted-card-entry-url>",
    "expiresAt": "2026-01-01T00:00:00Z"
  }
}

Keep the enrollment ID. You need it in the next two steps and at every checkout.

Send the user to the hosted card entry page

This step applies to all sources. Redirect the user to nextAction.url before expiresAt passes, and the user enters the card on a page hosted by Reap. Card details never reach your servers.Reap sends the user back to the returnUrl you supplied. Returning to that URL means the hosted page is finished. It does not mean the card is stored, so confirm the status next.

Confirm the enrollment is ACTIVE

Read the enrollment with GET /agentic/enrollments/:id after any hosted step.

Request

curl --request GET \
  --url https://sandbox.api.reap.global/agentic/enrollments/:id \
  --header 'Authorization: Bearer <token>' \
  --header 'Reap-Version: <reap-version>'

Response

{
  "id": "<enrollment-id>",
  "status": "ACTIVE",
  "owner": {
    "type": "REAP_USER",
    "id": "<user-id>",
    "email": "jsmith@example.com"
  },
  "paymentMethod": {
    "type": "CARD",
    "network": "<network>",
    "last4": "4242",
    "expiryMonth": 11,
    "expiryYear": 2029
  },
  "nextAction": null,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}

A status of ACTIVE means the card is ready to charge. A status of REQUIRES_ACTION means a hosted step is still outstanding, and nextAction tells you where to send the user. The paymentMethod block gives you the network and the last four digits to display in your own interface.

You can charge only an ACTIVE enrollment. Read the enrollment before you open a checkout rather than assuming the hosted page succeeded.

Present the available enrollment cards to the user

List the enrollments of one owner with GET /agentic/enrollments and show each stored card so the user can pick one. The paymentMethod block carries the network, the last four digits, and the expiry to display. Scope every list call to a single owner.

Request

curl --request GET \
  --url 'https://sandbox.api.reap.global/agentic/enrollments?ownerType=REAP_USER&ownerId=:id&limit=20' \
  --header 'Authorization: Bearer <token>' \
  --header 'Reap-Version: <reap-version>'

Response

{
  "items": [
    {
      "id": "<enrollment-id>",
      "status": "ACTIVE",
      "owner": {
        "type": "REAP_USER",
        "id": "<user-id>",
        "email": "jsmith@example.com"
      },
      "paymentMethod": {
        "type": "CARD",
        "network": "<network>",
        "last4": "4242",
        "expiryMonth": 11,
        "expiryYear": 2029
      },
      "nextAction": null,
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  ],
  "nextCursor": null
}

Follow nextCursor when it holds a value. A null cursor means the last page.

Test cards

Use these test cards on the hosted card entry page to run the full payment flow in the sandbox. They behave like real cards but never move money. Reap adds more cards and networks as it supports them.

These cards only work through the Agentic Payments API and are declined everywhere else.

Card number	CVC	Expiry
4622 9431 2313 7797	640	12/27
4622 9431 2313 7805	304	12/27
4622 9431 2313 7847	698	12/27

One-time passwords

The card verification step may ask for a one-time password. Enter 456789. The same code works whether you choose email or SMS delivery.

Next steps

One-Time Purchases

Run a single purchase against the enrollment you created.

Lifecycle and Statuses

Revoke a stored card and read every status value.

Field level detail for every field, header, and error sits in the API Reference tab. This page carries the sequence rather than repeating that detail.

Getting Started

Program Configuration

Compliance

Accounts

Cards

Transactions

Spend Policies

Virtual Assets

Statements

Agentic Payments

Rewards

Before you start

Store a card

Present the available enrollment cards to the user

Test cards

One-time passwords

Next steps

One-Time Purchases

Lifecycle and Statuses

​Before you start

​Store a card

​Present the available enrollment cards to the user

​Test cards

​One-time passwords

​Next steps

One-Time Purchases

Lifecycle and Statuses

Before you start

Store a card

Present the available enrollment cards to the user

Test cards

One-time passwords

Next steps