Skip to main content
Migo Docs

Frequently Asked Questions

Getting started​

How do I get API credentials?​

Contact your Migo account manager. Credentials are issued per environment (QA + production).

What languages / SDKs do you support?​

The only SDK documented in this portal is the Tap to Phone Android SDK (package com.migo.sdkmigo, minSdk 29); its installation is covered in SDK Install. There is no iOS version.

For everything else, the documented path is generating a typed client from the OpenAPI specs published in the API Reference β€” for example with openapi-typescript (TypeScript), oapi-codegen (Go), or openapi-python-client (Python).

If you need a native library beyond those, check with your Migo account manager what is available for your integration.

Is there a sandbox?​

Yes. See Environments & Base URLs. All features work in sandbox with test cards β€” see Testing Your Integration.

Authentication​

How long do access tokens last?​

For the merchant/client gateway, access tokens last 30 minutes and refresh tokens last 7 days. Wallet user-token lifetimes are configurable per partner/session rules (driven by the configuration service), not fixed values.

Refresh tokens?​

Single-use. Every refresh rotates both access and refresh tokens. Discard the old refresh token immediately.

What happens if I lose the refresh token?​

Re-log-in to obtain a new token pair. If you've forgotten your password, use the password-reset flow: request a one-time code via POST /users/auth/otp, then call POST /users/auth/password/reset.

Payments​

What's the difference between one-step and two-step payments?​

  • One-step β€” authorize + capture in a single request. Use for retail.
  • Two-step β€” authorize now, capture later (up to 7 days). Use for marketplaces, hospitality, pre-orders.

For card acceptance, charges run through the hosted checkout of a Payment Link.

When do I receive funds?​

Capture β†’ settled: next business day after 23:30 UTC cutoff. Settled β†’ in merchant's bank: T+1 to T+3 depending on the issuing bank.

Do you support Apple Pay / Google Pay?​

At the POS via contactless (NFC), yes. Provisioning Migo-issued cards into Apple/Google Pay wallets: planned, not yet shipped.

What about installments?​

Installment support is issuer-dependent β€” contact support to confirm availability for your terminal configuration. The documented CreateTerminalPaymentInput body does not expose a top-level installments field.

Webhooks​

Which events can I receive?​

Payment webhooks notify your commerce's terminal payments: terminal.payment.approved and terminal.payment.denied. Cancellations and reversals emit no events. The /webhooks/volcan and /webhooks/settlements endpoints are something else: they receive inbound calls from processors.

Will I receive duplicate events?​

Yes β€” delivery is at-least-once and the same event can arrive more than once. Always deduplicate by the event id (equal to the X-Migo-Event-Id header).

How do I verify the signature?​

Compute the HMAC-SHA256 of t + "." + raw body with the webhook secret, compare it in constant time with the v1 of the X-Migo-Signature header, and reject the event if t is more than 300 seconds away from the current time. Full guide, with Node.js and Python samples, in Verify the Signature.

How long does Migo retry failed deliveries?​

About 33 hours: 7 attempts in total, waiting 5 minutes, 15 minutes, 30 minutes, 2 hours, 6 hours and 24 hours between them. A delivery succeeds when your endpoint answers 2xx within 10 seconds. See Retries.

Can I pause event delivery?​

Yes: send a PATCH with { "enabled": false } to the webhook and set it back to true to resume it; the secret does not change. While paused it receives no new events. See Update, Pause or Resume.

Subscriptions​

Is the first charge automatic?​

A subscription is created through the card-verification flow (POST /api/v1/subscriptions/verify-card with shouldCreateSubscription=true), which internally creates the subscription. There is no public POST /api/v1/subscriptions endpoint and no startAt parameter.

What if a scheduled charge fails?​

Failed renewals are handled by a grace-period model (renewal status tracking), not a fixed retry ladder. A subscription's terminal status is inactive or expired β€” there is no unpaid status. The exact grace-period cadence is configurable; contact support to confirm the values for your account.

Can I charge outside the schedule?​

Yes β€” Variable-amount charges.

Cards & wallet​

Do Migo-issued cards work with Apple / Google Pay?​

Provisioning is planned, not yet shipped. Once live, card push provisioning via the Wallet SDK will be supported.

How do I retrieve a CVV?​

Two-step: request a view token, then use it in the CVV GET from the mobile client. Never from your backend.

Can a card belong to multiple users?​

Yes β€” per-user permissions control who can do what. See Cardholder management.

Compliance​

What's Migo's PCI-DSS scope?​

Level 1 Service Provider. See Security & PCI scope.

Where is data stored?​

Primary region: AWS us-east-1, with a secondary region in AWS us-east-2. For data-residency, GDPR, and regional-compliance specifics, contact legal.

Can I get a SOC 2 report?​

Yes β€” under NDA. Contact your Migo account manager.

Errors​

I got a 7604 INVALID_SIGNATURE β€” what's wrong?​

Your request signature did not validate. The most common cause is that the JSON body was re-serialized before signing, changing the byte content. Sign the raw body bytes and verify your signing keys are current.

I got a 7616 KEYS_EXPIRED β€” what does this mean?​

Your signature keys have expired. Rotate them and authenticate again.

What does 7303 INSUFFICIENT_FUNDS mean?​

The source account does not have enough balance to complete the transaction. See the full Error catalog for every code and its HTTP status.