yuno / stripe / token migration
Merchant Migration Guide

Enroll Stripe payment methods in Yuno.

You've already created your customers in Yuno. This guide walks through enrolling their existing Stripe payment methods directly into Yuno's vault, no re-entry, no reauthorization, no checkout session required.

You send
pm_stripe_xyz123
→
Yuno enrolls
POST /payment-methods
→
Yuno returns
cbdcc878-ceb4-4dd8…
The flow

Four steps, run once per payment method

Enrollment is a direct, synchronous call. There's no session and no customer interaction, so the whole migration is a batch job you control end to end.

1

Call the enrollment API

Send one POST request per payment method, with the Stripe token in provider_data.

2

Handle the response

On success, store the vaulted_token. On failure, log the reason and keep moving.

3

Respect the rate limit

Stay under 6,000 requests/min. Batch in small chunks and back off on 429.

4

Loop until done

Repeat for every payment method, tracking successes, failures, and elapsed time.

Step 1

Call the enrollment API

One request per payment method. customer_id identifies who the method belongs to and travels in the URL, not the body.

endpoint
POST https://api-sandbox.y.uno/v1/customers/{customer_id}/payment-methods  ← sandbox
POST https://api.y.uno/v1/customers/{customer_id}/payment-methods           ← production
Path, not body

customer_id is a path parameter. It's the Yuno customer ID you received when creating the customer, it belongs in the URL. Put it in the request body instead and the call fails.

headers (all required)
Content-Type
application/json
public-api-key
<your-public-api-key>
private-secret-key
<your-private-secret-key>
X-Idempotency-Key
<unique UUID per request>
request body
{
  "account_id": "your-account-id",
  "country": "US",
  "type": "CARD",
  "provider_data": {
    "id": "Stripe",
    "payment_method_token": "pm_stripe_xyz123"
  }
}
curl, sandbox
curl --request POST \
  --url https://api-sandbox.y.uno/v1/customers/{customer_id}/payment-methods \
  --header 'Content-Type: application/json' \
  --header 'public-api-key: <your-public-api-key>' \
  --header 'private-secret-key: <your-private-secret-key>' \
  --header 'X-Idempotency-Key: <unique-uuid>' \
  --data '{
    "account_id": "your-account-id",
    "country": "US",
    "type": "CARD",
    "provider_data": {
      "id": "Stripe",
      "payment_method_token": "pm_stripe_xyz123"
    }
  }'
Step 2

Handle the response

Every call resolves immediately, success or failure. Nothing here is asynchronous.

✓ success · HTTP 200
{
  "status": "ENROLLED",
  "vaulted_token": "cbdcc878-ceb4-4dd8-
    b0f0-49d444855de0",
  "card_data": {
    "brand": "VISA",
    "iin": "41111111",
    "lfd": "1111"
  }
}
✗ error · HTTP 4xx / 5xx
  • Invalid customer_id in the URL path
  • Invalid account_id in the body
  • Invalid Stripe token format
  • HTTP 429, rate limit hit, see step 3
What to keep

Store the vaulted_token from every success. It's your Yuno reference for all future payments against that method.

Step 3

Rate limit: 6,000 requests/min

Roughly 100 requests per second. Migrations of any real size need to be paced, not fired all at once.

50,000 methods ÷ 100/sec = 500 sec (~8 min)

Batch in small chunks: send 50-100 requests, pause, repeat.

On 429

Implement exponential backoff and retry. Don't just resend immediately, that compounds the throttling.

Step 4

Loop through all payment methods

Repeat step 1 for every payment method in the migration set. Track three things as you go:

Before you build

Checklist