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.
Relatedβ
- Error catalog for every code
- Contact for direct support