Skip to main content
Getting startedGuide

A sandbox payment that succeeds is the starting point. Work through these five steps with your engineering and operations teams before you send real transactions.

Activate Live ModePublish a live routeVerify webhooksRun a real payment and refund
1

Activate Live Mode and switch to production keys

Your organization starts with access to Test Mode only. To get Live Mode, submit an activation request from the dashboard home page. The organization status changes from “Inactive” to “Under Verification”, and Test Mode stays available while Yuno verifies the account. See Environments.When Live Mode is enabled:
  • Copy the Live keys from Developers. Yuno keeps separate keys for Test and Live. See Developers credentials.
  • Check the key prefix. Sandbox keys start with sandbox_ and production keys start with prod_. The Yuno SDK picks the environment from this prefix. See Get started with the Yuno SDK.
  • Point your server at the production base URL of your region, listed on Developers. Each organization belongs to one region, and data is not shared between regions.
  • Keep the private-secret-key on your server and out of public places such as a GitHub repository. See Authentication.
2

Connect a live provider and publish the route

The Yuno Test Payment Gateway works in sandbox only, so production payments need a connection to a real provider.
  1. With the context chip set to Live, open Connections and connect each provider you launch with.
  2. Open Routing and check the Not published tab. Every payment method that has a connection but no route is listed there.
  3. Create the route, add the provider step, and click Publish. See Routing.
  4. Open Checkout builder, turn on the payment methods that have a published route, and click Publish settings. Changes stay Not published until you publish them.
3

Set up the production webhook and safe retries

Confirm the outcome of each payment on your server, from a webhook or from the payments API, before you fulfill the order.
  • Configure a production webhook with a public HTTPS URL that returns HTTP 200. Yuno retries a delivery that does not get HTTP 200, so the same event can arrive more than once. Refund and chargeback events carry the same data.payment.idempotency_key as their payment, so record each processed event under its account_id, type_event, and idempotency key together, and skip an event that is already recorded. See De-duplication.
  • Turn on Use HMAC Authentication and verify the x-hmac-signature header against the raw request body, before you parse the JSON, with the secret configured for that webhook. See Verify webhook signatures.
  • Send an X-Idempotency-Key when you create a payment. If the outcome is unclear (a timeout, a connection error, or a 500), retry with the same key. A 400 REQUEST_IN_PROCESS means the first request is still running, so retry with the same key after a few seconds. A 400 IDEMPOTENCY_DUPLICATED means no payment exists for that key, so correct the request and send it with a new key. See Idempotency.
  • Use Retrieve payment to recover the state of a payment when a webhook or a request outcome is unclear.
4

Decide on 3DS and your PCI scope

3D Secure. You decide whether your card payments use 3DS2. You add the 3DS step to a Card route before the provider step, under Routing > Card Routes > 3DS Step. 3DS DIRECT also needs acquirer data: an acquirer BIN per card brand, the merchant ID, the MCC, the merchant name and URL, and the country code. See 3D Secure.PCI DSS. With the Yuno SDK (or the legacy Full, Lite, or Secure Fields SDKs), card data goes from the customer’s browser or app to Yuno and your servers receive only tokens, so most merchants qualify for SAQ A. If your server sends raw card numbers, as the DIRECT workflow in the Quickstart does, your systems are in PCI DSS scope. See PCI compliance.
5

Run a real payment and refund, then watch the first payments

Test cards belong to the sandbox. In Live Mode, run a low-value payment with a real card through each provider and payment method you launch, then refund it.
  • Refund with Refund payments. Each refund call needs an X-Idempotency-Key with a new value per attempt. Wait for a refund to reach SUCCEEDED, DECLINED, or ERROR before you start another one on the same transaction.
  • Whether a refund is confirmed at once or stays PENDING, and whether partial refunds are allowed, depends on the provider. Check the behavior of each provider you launch with.
  • Open Payments in the dashboard in Live Mode to see every payment and transaction, filter them, and export reports. See Payments.
  • Check service status for incidents, and write to support@y.uno with the payment ID when a result does not match what you expect.

​
Test beyond the happy path

Before launch, show that your application handles each of these cases. Use the Yuno Testing Gateway in sandbox and the testing instructions of each provider. Sandbox results do not prove how every live provider behaves.

​
Next

  1. TroubleshootingReference The response, its cause, and the fix for the errors a new integration hits first.
  2. WebhooksGuide Delivery, retries, de-duplication, and the pages to configure and verify a webhook.
  3. Payment flowConcept Each step of a payment, field by field.
  4. Create paymentReference The request and response schema for the call that creates a payment.