diff --git a/SDKs/Card Enrollment/_order.yaml b/SDKs/Card Enrollment/_order.yaml new file mode 100644 index 000000000..2e4ef4adb --- /dev/null +++ b/SDKs/Card Enrollment/_order.yaml @@ -0,0 +1,3 @@ +- android-enrollment +- ios-enrollment +- web-enrollment diff --git a/SDKs/Card Enrollment/android-enrollment.md b/SDKs/Card Enrollment/android-enrollment.md new file mode 100644 index 000000000..280fed637 --- /dev/null +++ b/SDKs/Card Enrollment/android-enrollment.md @@ -0,0 +1,160 @@ +--- +title: Enrollment Flows +deprecated: false +hidden: false +metadata: + robots: index +--- + +The Android SDK makes it easy to implement enrollment flows for saving payment methods to a customer account. + +Include the library in your project by following the same steps as in [Full Checkout](android-payments#include-the-library-in-your-project). + +## Additional resources + +- See [Choose the right integration for you](choose-your-integration) if you're unsure which flow to follow. +- Access the [Release notes](release-notes-android) or the [Yuno Android SDK repository](https://github.com/yuno-payments/yuno-sdk-android) to verify the latest SDK version available. + +- [Full Checkout Enrollment (Android)](#full-checkout-enrollment-android): Automatic enrollment with pre-built UI components + +## Requirements + +* **Minimum SDK Version**: `minSdkVersion` 21 or above +* **Java**: Java 8 enabled +* **AndroidX**: Use AndroidX instead of older support libraries +* **Android Gradle Plugin**: 4.0.0 or above +* **ProGuard**: 6.2.2 or above +* **Kotlin Gradle Plugin**: 1.4.0 or above +* **ELF Page Size Support**: Compliant with Google's 16 KB ELF page alignment requirements (Android 15 / ARMv9 ready) +* Active Yuno account +* API credentials (obtain from the [Yuno Dashboard](https://dashboard.y.uno/) β†’ **Developers** > **Credentials**) +* Create a customer using the [Create customer endpoint](ref:create-customer) before enrolling + +## Parameters + +For the full list of parameters, see the [Android SDK Common Reference](android-sdk-common-reference). + +| Parameter | Description | +|-----------|-------------| +| `customerSession` | Customer session ID from Create customer session API. Required. | +| `countryCode` | ISO country code. Required. | +| `showEnrollmentStatus` | Show enrollment result screen. Optional; default true. | +| `callbackEnrollmentState` | Callback: enrollment state. Optional; requires `initEnrollment` in onCreate. | +| `requestCode` | Optional; use if capturing result via `onActivityResult`. | +| `countryCode` | Country for the enrollment. Required for `apiClientEnroll`. | +| `customerSession` | Customer session ID. Required for `apiClientEnroll`. | + +## Full Checkout Enrollment (Android) + +Yuno Full Checkout for Android provides enrollment with pre-built UI, card enrollment, status handling, and basic error management. See [Requirements](#requirements) above. + +### Step 1: Create a customer + +Create a customer in Yuno's system using the [Create customer endpoint](ref:create-customer) before enrolling payment methods. This endpoint returns a `customer_id`. Then create a customer session using the [Create Customer Session](ref:create-customer-session) endpoint; use the returned `customer_session` when calling the enrollment methods. + +### Step 2: Include the library in your project + +Add the Yuno library to your Android project: + +#### Add the Repository + +Add Yuno's Maven repository to your project's Gradle configuration: + +```kotlin +maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" } +``` + +Add the dependency in `build.gradle`: + +```kotlin +dependencies { + implementation 'com.yuno.payments:android-sdk:2.11.0' +} +``` + +#### Permissions + +The Yuno SDK includes the `INTERNET` permission by default, which is required to make network requests. + +```xml + +``` + +### Step 3: Initialize SDK with the public key + +Initialize the SDK: + +1. Get your Public API Key from the [Yuno Dashboard](https://dashboard.y.uno/) +2. Create a custom application class if you haven't already done so +3. In the `onCreate()` method of your application class, call `Yuno.initialize()` with your API key: + +```kotlin +class CustomApplication : Application() { + override fun onCreate() { + super.onCreate() + Yuno.initialize( + this, + PUBLIC_API_KEY, + config = YunoConfig(), + ) + } +} +``` + +Use the data class `YunoConfig` to customize the SDK's behavior. Include this configuration when calling `Yuno.initialize()`. The available options are: + +```kotlin +data class YunoConfig( + val saveCardEnabled: Boolean = false, + val keepLoader: Boolean = false, + val cardFormDeployed: Boolean = false, + val language: YunoLanguage? = null, + val styles: YunoStyles? = null +) +``` + +> 🚧 cardFlow removed from YunoConfig +> +> Starting from version **2.11.0**, `cardFlow` is no longer part of `YunoConfig`. Card flow configuration is now handled exclusively through the **CheckoutBuilder**. + +### Step 4: Enroll a new payment method + +The enrollment process is a two-step flow. First, initialize the process to set up the necessary components. Then, start the UI flow to allow the user to enroll a payment method. + +#### 4.1 Initialize the enrollment process + +Call the `initEnrollment` method within your activity's `onCreate` method to prepare your app to handle the enrollment flow. This is a mandatory setup step required by the Android operating system to register the contract that allows the SDK to send the final enrollment status back to your app. + +```kotlin +fun ComponentActivity.initEnrollment( + callbackEnrollmentState: ((String?) -> Unit)? = null +) +``` + +#### 4.2 Start the enrollment flow + +Call the `startEnrollment` method to launch the user interface and begin the enrollment of a new payment method. You can call this method at any point after `initEnrollment` has been executed, such as when a user taps an "Enroll New Payment Method" button. + +```kotlin +fun Activity.startEnrollment( + customerSession: String, + countryCode: String, + showEnrollmentStatus: Boolean = true, + callbackEnrollmentState: ((String?) -> Unit)? = null, + requestCode: Int +) +``` + +`startEnrollment` parameters: + +| Parameter | Description | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `customerSession` | The session customer associated with the current enrollment process. | +| `countryCode` | Country code where the payment is performed. See [Country coverage](country-coverage) for a complete list of supported countries and their codes. | +| `showEnrollmentStatus` | Indicates whether the enrollment status should be shown. This parameter is optional and defaults to `true`. | +| `callbackEnrollmentState` | A function that returns the current state of the enrollment process. This parameter is optional and defaults to `null`. To register this callback, you must call `initEnrollment` method in the `onCreate` method of the activity. Check the possible states that can be returned. | +| `requestCode` | It is an optional parameter you must inform if you are going to use the `onActivityResult` method to capture the enrollment states. | + +## Common reference + +For full parameter and customization details, see the [Android SDK Common Reference](android-sdk-common-reference). \ No newline at end of file diff --git a/docs/Yuno SDKs/ios-sdks/copy-of-enrollment-flows.md b/SDKs/Card Enrollment/ios-enrollment.md similarity index 68% rename from docs/Yuno SDKs/ios-sdks/copy-of-enrollment-flows.md rename to SDKs/Card Enrollment/ios-enrollment.md index d0c9e6988..bd42a8f4c 100644 --- a/docs/Yuno SDKs/ios-sdks/copy-of-enrollment-flows.md +++ b/SDKs/Card Enrollment/ios-enrollment.md @@ -1,21 +1,21 @@ --- -title: Copy of Enrollment Flows +title: Enrollment Flows deprecated: false -hidden: true +hidden: false metadata: robots: index --- + The iOS SDK makes it easy to implement enrollment flows for saving payment methods to a customer account. -Include the library in your project by following the same steps as in [payment flows](payment-flows-ios#include-the-library-in-your-project). This lets you complete [step 2](#step-2-include-the-library-in-your-project) and continue with the enrollment flow below. +Include the library in your project by following the same steps as in [Full Checkout](ios-payments#include-the-library-in-your-project). ## Additional resources - See [Choose the right integration for you](choose-your-integration) if you're unsure which flow to follow. - Access the [Release notes](release-notes-ios) or the [Yuno iOS SDK repository](https://github.com/yuno-payments/yuno-sdk-ios) to verify the latest SDK version available. -- [Lite Enrollment (iOS)](#lite-enrollment-ios): Lightweight enrollment with UI control and backend support -- [Headless Enrollment (iOS)](#headless-enrollment-ios): Full enrollment experience customization without requiring PCI compliance +- [Full Checkout Enrollment (iOS)](#full-checkout-enrollment-ios): Automatic enrollment with pre-built UI components ## Requirements @@ -35,11 +35,11 @@ For the full list of parameters, see the [iOS SDK Common Reference](ios-sdk-comm | `language` | Language code for the UI. Optional. | | `viewController` | UIViewController that presents the enrollment flow. Required for delegate. | | `yunoEnrollmentResult(_:)` | Delegate: enrollment finished with result. | -| `YunoConfig` (initialize) | Optional: appearance, saveCardEnabled, keepLoader. See Common Reference. | +| `YunoConfig` (initialize) | Optional: appearance, saveCardEnabled, keepLoader, hideCardholderName. See Common Reference. | -## Lite Enrollment (iOS) +## Full Checkout Enrollment (iOS) -The Yuno Lite iOS SDK provides enrollment with pre-built UI, card enrollment, status handling, and basic error management. Use it when you need minimal customization and a ready-to-use enrollment flow. See [Requirements](#requirements) above. +The Yuno Full Checkout iOS SDK provides enrollment with pre-built UI, card enrollment, status handling, and basic error management. See [Requirements](#requirements) above. ### Step 1: Create a customer and customer session @@ -108,6 +108,7 @@ struct YunoConfig { var appearance: Appearance? = nil var saveCardEnabled: Bool = false var keepLoader: Bool = false + var hideCardholderName: Bool = false } ``` @@ -244,108 +245,6 @@ func yunoEnrollmentResult(_ result: Yuno.Result) { For styling, themes, form options, and additional configurations, see [SDK customizations](ios-customizations). -## Headless Enrollment (iOS) - -Headless (iOS) lets you enroll payment methods and tokenize cards for future use, with full control over the UI and direct API access. See [Requirements](#requirements) above. - -### Step 1: Create a customer and customer session - -Create a customer using the [Create Customer](ref:create-customer) endpoint before enrolling payment methods. Then create a new `customer_session` using the [Create Customer Session](ref:create-customer-session) endpoint and store the `customer_session` ID for the enrollment calls. - -```json -POST /v1/customer-session - -{ - "country": "BR", - "customer_id": "6c85a4e3-0a6c-423d-a12a-10045320ab4a" -} -``` - -### Step 2: Add the SDK to your project - -Including the library in your project is done in the same way as in payment flows. Follow the steps in [Include the library in your project](payment-flows-ios#include-the-library-in-your-project) there. - -#### CocoaPods - -```ruby -pod 'YunoSDK', '~> 2.11.1' -``` - -Run: - -```ruby -pod install -``` - -#### Swift Package Manager - -```swift -dependencies: [ - .package(url: "https://github.com/yuno-payments/yuno-sdk-ios.git", .upToNextMajor(from: "2.11.1")) -] -``` - -### Step 3: Initialize Headless with the public key - -Retrieve your public API keys from the [Yuno Dashboard](https://dashboard.y.uno/). Then initialize the SDK: - -```swift -import YunoSDK - -Yuno.initialize( - apiKey: "PUBLIC_API_KEY" -) -``` - -### Step 4: Start the enrollment process - -Use `Yuno.apiClientEnroll` to configure the headless enrollment client: - -```swift -var apiClientEnroll: YunoEnrollHeadless? - -apiClientEnroll = try Yuno.apiClientEnroll( - countryCode: "CO", - customerSession: "eec6578e-ac2f-40a0-8065-25b5957f6dd3" -) -``` - -### Step 5: Generate a vaulted token - -After collecting all user information, create a `vaulted_token` using `apiClientEnroll.continueEnrollment(data:)`. Use `do/catch` to handle errors: - -```swift -let enrollmentCollectedData: EnrollmentCollectedData = EnrollmentCollectedData( - customerSession: "eec6578e-ac2f-40a0-8065-25b5957f6dd3", - paymentMethod: CollectedData( - type: "CARD", - card: CardData( - detail: CardData.Detail( - number: "4111111111111111", - expirationMonth: 12, - expirationYear: 25, - securityCode: "123", - holderName: "Andrea", - type: .credit - ) - ), - customer: Customer() - ) -) - -let result = try await apiClientEnroll.continueEnrollment(data: enrollmentCollectedData) -``` - -After enrolling the new card, you receive the `vaulted_token` and enrollment status in the result, which you can use for future payments or to update your customer records. - -**When to use Headless Enrollment:** -- You need complete control over the enrollment UI -- You have specific design requirements -- You're building a highly customized enrollment experience - -### Complementary features - -For styling, themes, form options, and additional configurations, see [SDK customizations](ios-customizations). ## Common reference diff --git a/SDKs/Card Enrollment/web-enrollment.md b/SDKs/Card Enrollment/web-enrollment.md new file mode 100644 index 000000000..97c58c352 --- /dev/null +++ b/SDKs/Card Enrollment/web-enrollment.md @@ -0,0 +1,260 @@ +--- +title: Enrollment Flows +deprecated: false +hidden: false +metadata: + robots: index +--- +The Web SDK makes it easy to implement enrollment flows for saving payment methods to a customer account. + +Include the library in your project by following the same steps as in [payment flows](payment-flows-web#include-the-library-in-your-project). This lets you complete [step 1](#step-1-include-the-library-in-your-project) and continue with the enrollment flow below. + +## Additional resources + +* Yuno offers a [TypeScript library](https://www.npmjs.com/package/@yuno-payments/sdk-web-types) that complements the SDK. + +* See [Choose the right integration for you](choose-your-integration) if you're unsure which flow to follow. + +* See the [Demo App](https://github.com/yuno-payments/yuno-sdk-web) for a complete implementation (clone from the repository). + +## Requirements + +* A [customer](ref:create-customer) created in Yuno, a [customer session](ref:create-customer-session), and an [enrollment payment method object](ref:enroll-payment-method-checkout): reference each API when setting up your backend. +* Public API key (obtain from the [Yuno Dashboard](https://dashboard.y.uno/) β†’ **Developers** > **Credentials**) + +## Parameters + +For the full list of parameters and callbacks, see the [Web SDK Common Reference](web-sdk-common-reference). + +| Parameter | Description | +| ---------------------- | ------------------------------------------------------------------------------ | +| `customerSession` | Customer session ID from your backend (Create customer session API). Required. | +| `countryCode` | ISO country code (e.g. `US`). | +| `language` | Language code for the UI (e.g. `en`). Optional. | +| `showLoading` | Show loading spinner. Optional. | +| `onLoading` | Callback: loading state updates. Optional. | +| `elementSelector` | CSS selector where the enrollment form mounts. Optional. | +| `card` | Card form options. Optional. | +| `yunoEnrollmentStatus` | Callback: enrollment ended; receives `vaultedToken` and `status`. | +| `issuersFormEnable` | Show issuer (bank) list. Optional. | +| `texts` | Custom button/label text. Optional. | + +## Full Checkout Enrollment (Web) + +Use Full Checkout for a seamless integration with pre-built UI. Implement enrollment as follows. + +### Step 1: Include the library in your project + +Including the library in your project is done in the same way as in [payment flows](payment-flows-web#include-the-library-in-your-project). + +### Step 2: Initialize the SDK + +See [Quickstart guide](quickstart-guide#web-sdk-integration) for initialization. + +### Step 3: Create a customer session and an enrollment payment method object + +Create a [customer session](ref:create-customer-session) and an [enrollment payment method object](ref:enroll-payment-method-checkout) on your **server-side** to keep private API keys secure; define which payment method the customer can enroll when creating the payment method object. + +#### Server-side example + +Create a customer session and enrollment payment method on your backend. This keeps your private API keys secure. + +```javascript +// 1. Create customer session +const customerSession = await fetch( + "https://api-sandbox.y.uno/v1/customers/sessions", + { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${PRIVATE_SECRET_KEY}`, + }, + body: JSON.stringify({ + customer_id: "your-customer-id", + country: "US", + }), + } +).then((res) => res.json()); + +// 2. Create enrollment payment method +const enrollment = await fetch( + `https://api-sandbox.y.uno/v1/customers/sessions/${customerSession.id}/payment-methods`, + { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${PRIVATE_SECRET_KEY}`, + }, + body: JSON.stringify({ + type: "CARD", + }), + } +).then((res) => res.json()); + +// Return customerSession to your client +return customerSession; +``` + +#### Client-side example + +After receiving the `customerSession` from your server, initialize the Yuno SDK and mount the enrollment form on the client-side. + +```javascript +// Initialize Yuno SDK +const yuno = await Yuno.initialize(PUBLIC_API_KEY); + +// Mount the enrollment form +yuno.mountEnrollment({ + customerSession, // Received from your server + countryCode: "US", + language: "en", + showLoading: true, + onLoading: (args) => { + console.log(args); + }, +}); +``` + +To verify cards (zero-value authorization) before enrollment, add the `verify` struct when defining the payment method object on the server. + +### Step 4: Mount the enrollment + +Use `yuno.mountEnrollment` with the parameters below. + +| Parameter | Description | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `customerSession` | Refers to the current enrollment's [customer session](ref:create-customer-session). Example: `e15648b0-fcd5-4799-a14c-cc463ae8a133`. | +| `countryCode` | Country for the payment process. Use an `ENUM` value; see [Country Coverage](country-coverage). | +| `language` | Language for payment forms. Use any code listed in [Supported languages](languages-supported). Example: `en-US`. Defaults to browser language when available. | +| `showLoading` | Controls visibility of the Yuno loading/spinner page during the payment process. | +| `onLoading` | Required to receive notifications about server calls or loading events. | +| `elementSelector` | HTML element where the Yuno SDK is mounted. | +| `card` | Define specific settings for the credit card form. | +| `yunoEnrollmentStatus` | Callback after enrollment ends; receives `vaultedToken` and `status`. Status options: `CREATED`, `EXPIRED`, `REJECTED`, `READY_TO_ENROLL`, `ENROLL_IN_PROCESS`, `UNENROLL_IN_PROCESS`, `ENROLLED`, `DECLINED`, `CANCELED`, `ERROR`, `UNENROLLED`. | +| `issuersFormEnable` | Enable the issuer's form (bank list). | +| `texts` | Custom text for payment form buttons to match your application's language or branding. | +| `card.isCreditCardProcessingOnly` | Optional. Forces card transactions to process as credit onlyβ€”useful where cards act as both credit and debit. | + +The next code block presents an example of the Enrollment parameter configuration and mounting. + +```javascript +yuno.mountEnrollment({ + customerSession: 'e15648b0-fcd5-4799-a14c-cc463ae8a133', + /** + * The complete list of country codes is available on https://docs.y.uno/docs/country-coverage + */ + countryCode: country, + /** + - Language for payment forms (see Supported languages) + - Defaults to browser language when available + */ + language: 'en-US', + /** + * Hide or show the Yuno loading/spinner page + * Default is true + * @optional + */ + showLoading: true, + /** + * Required if you'd like to be informed if there is a server call + * @param { isLoading: boolean, type: 'DOCUMENT' | 'ONE_TIME_TOKEN' } data + * @optional + */ + onLoading: (args) => { + console.log(args); + } + /** + * API card + * @optional + */ + card: { + /** + * Mode render card can be step or extends + * Default extends + */ + type: "extends", + /** + * Write custom CSS to style the card form. Your CSS will be injected into the iframe. + * Example: + * `@import url('https://fonts.googleapis.com/css2?family=Luckiest+Guy&display=swap'); + * .Yuno-front-side-card__name-label { + * color: red !important; + * font-family: 'Luckiest Guy' !important; + * }` + */ + styles: '', + /** + * Show checkbox for save/enroll card + * Default is false + */ + cardSaveEnable: false, + /** + * Custom texts in Card forms buttons + * Example: + * + * texts: { + * cardForm?: { + * enrollmentSubmitButton?: string; + * paymentSubmitButton?: string; + * } + * cardStepper?: { + * numberCardStep?: { + * nextButton?: string; + * }, + * cardHolderNameStep?: { + * prevButton?: string; + * nextButton?: string; + * }, + * expirationDateStep?: { + * prevButton?: string; + * nextButton?: string; + * }, + * cvvStep?: { + * prevButton?: string; + * nextButton?: string; + * } + * } + * } + */ + texts: {}, + /** + * Hide or show the document fields into card form + * Default is true + * @optional + */ + documentEnable: true, + }, + /** + * Call back is called with the following object + * @param {{ + * status: 'CREATED' + * | 'EXPIRED', + * | 'REJECTED', + * | 'READY_TO_ENROLL', + * | 'ENROLL_IN_PROCESS', + * | 'UNENROLL_IN_PROCESS', + * | 'ENROLLED', + * | 'DECLINED', + * | 'CANCELED', + * | 'ERROR', + * | 'UNENROLLED', + * vaultedToken: string, + * }} + */ + yunoEnrollmentStatus: ({ status, vaultedToken}) => { + console.log('status', { status, vaultedToken}) + }, + /** + * If this is called the SDK should be mounted again + * @param { error: 'CANCELED_BY_USER' | any } + * @optional + */ + yunoError: (error) => { + console.log('There was an error', error) + }, +}); +``` + +## Common reference + +For full parameter and customization details, see the [Web SDK Common Reference](web-sdk-common-reference). diff --git a/SDKs/Customization/_order.yaml b/SDKs/Customization/_order.yaml new file mode 100644 index 000000000..1d0a1f282 --- /dev/null +++ b/SDKs/Customization/_order.yaml @@ -0,0 +1,3 @@ +- android +- ios +- secure-fields diff --git a/docs/Yuno SDKs/android-sdks/android-customizations.md b/SDKs/Customization/android.md similarity index 100% rename from docs/Yuno SDKs/android-sdks/android-customizations.md rename to SDKs/Customization/android.md diff --git a/docs/Yuno SDKs/ios-sdks/ios-customizations.md b/SDKs/Customization/ios.md similarity index 100% rename from docs/Yuno SDKs/ios-sdks/ios-customizations.md rename to SDKs/Customization/ios.md diff --git a/docs/Yuno SDKs/web-sdks/secure-fields/_order.yaml b/SDKs/Customization/secure-fields/_order.yaml similarity index 100% rename from docs/Yuno SDKs/web-sdks/secure-fields/_order.yaml rename to SDKs/Customization/secure-fields/_order.yaml diff --git a/docs/Yuno SDKs/web-sdks/secure-fields/enrollment-secure-fields.md b/SDKs/Customization/secure-fields/enrollment-secure-fields.md similarity index 100% rename from docs/Yuno SDKs/web-sdks/secure-fields/enrollment-secure-fields.md rename to SDKs/Customization/secure-fields/enrollment-secure-fields.md diff --git a/docs/Yuno SDKs/web-sdks/secure-fields/index.md b/SDKs/Customization/secure-fields/index.md similarity index 100% rename from docs/Yuno SDKs/web-sdks/secure-fields/index.md rename to SDKs/Customization/secure-fields/index.md diff --git a/docs/Yuno SDKs/web-sdks/secure-fields/payment-secure-fields.md b/SDKs/Customization/secure-fields/payment-secure-fields.md similarity index 100% rename from docs/Yuno SDKs/web-sdks/secure-fields/payment-secure-fields.md rename to SDKs/Customization/secure-fields/payment-secure-fields.md diff --git a/SDKs/Full Checkout/_order.yaml b/SDKs/Full Checkout/_order.yaml new file mode 100644 index 000000000..a240f7984 --- /dev/null +++ b/SDKs/Full Checkout/_order.yaml @@ -0,0 +1,3 @@ +- web-payments +- android-payments +- ios-payments diff --git a/SDKs/Full Checkout/android-payments.md b/SDKs/Full Checkout/android-payments.md new file mode 100644 index 000000000..1d455c7c6 --- /dev/null +++ b/SDKs/Full Checkout/android-payments.md @@ -0,0 +1,393 @@ +--- +title: Payment Flows +deprecated: false +hidden: false +metadata: + robots: index +--- +The Android SDK makes it easy to integrate payment flows into your Android app. + +## Additional resources + +* See [Choose the right integration for you](choose-your-integration) if you're unsure which flow to follow. +* Access the [Release notes](release-notes-android) or the [Yuno Android SDK repository](https://github.com/yuno-payments/yuno-sdk-android) to verify the latest SDK version available. + +## Requirements + +* **Minimum SDK Version**: `minSdkVersion` 21 or above +* **Java**: Java 8 enabled +* **AndroidX**: Use AndroidX instead of older support libraries +* **Android Gradle Plugin**: 4.0.0 or above +* **ProGuard**: 6.2.2 or above +* **Kotlin Gradle Plugin**: 1.4.0 or above +* **ELF Page Size Support**: Compliant with Google's 16 KB ELF page alignment requirements (Android 15 / ARMv9 ready) +* Active Yuno account +* Yuno API credentials (obtain from the [Yuno Dashboard](https://dashboard.y.uno/) β†’ **Developers** > **Credentials**) +* Create a `checkout_session` and the payment via the API; create a customer using the [Create customer endpoint](ref:create-customer) before creating a payment + +## Include the library in your project + +The first step is including the library in your project. Add the Yuno Android SDK to your project through Gradle. Add the repository source and dependency: + +```kotlin +maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" } +``` + +```kotlin +dependencies { + implementation 'com.yuno.payments:android-sdk:2.11.0' +} +``` + +Once Step 1 is complete, continue with the Full Checkout integration. + +## Parameters + +For the full list of parameters and YunoConfig details, see the [Android SDK Common Reference](android-sdk-common-reference). + +| Parameter | Description | +| ------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `checkoutSession` | Checkout session ID from your backend (Create checkout session API). Required. | +| `countryCode` | ISO country code (e.g. `US`). Required. | +| `callbackPaymentState` | Callback: payment state (e.g. SUCCEEDED, FAIL, PROCESSING, REJECT). | +| `merchantSessionId` | Optional merchant session identifier. | +| `YunoConfig` (initialize) | Optional: saveCardEnabled, cardFormDeployed, language, styles, placeholders. See Common Reference. | + +## Full Checkout + +Implement Full (Android): customizable UI, payment method management, fraud prevention, and checkout flows. More feature-rich than Headless, which focuses on core payment processing. See [Requirements](#requirements) above. + +### Step 1: Include the library in your project + +Follow the steps in [Include the library in your project](#include-the-library-in-your-project) above. + +### Step 2: Initialize SDK with the public key + +Retrieve your public API keys from the [Yuno Dashboard](https://dashboard.y.uno/). + +If you haven't implemented a custom application, create one. In the `onCreate()` method of your application class, call the initialize function (`Yuno.initialize`): + +```kotlin +class CustomApplication : Application() { + override fun onCreate() { + super.onCreate() + Yuno.initialize( + this, + "", + config = YunoConfig(), + ) + } +} +``` + +See the [credentials page](https://docs.y.uno/reference/authentication) for more information. Use the data class `YunoConfig` to customize the SDK's behavior. Include this configuration when calling `Yuno.initialize()`. The available options are: + +```kotlin +data class YunoConfig( + val saveCardEnabled: Boolean = false, + val cardFormDeployed: Boolean = false, + val language: YunoLanguage? = null, + val styles: YunoStyles? = null, + val cardNumberPlaceholder: String? = null, // Optional: Custom placeholder text for card number field + val hideCardholderName: Boolean? = null // Optional: Set to true to hide cardholder name field +) +``` + +> 🚧 cardFlow removed from YunoConfig +> +> Starting from version **2.11.0**, `cardFlow` is no longer part of `YunoConfig`. Card flow configuration is now handled exclusively through the **CheckoutBuilder**. If you are migrating from an earlier version, remove `cardFlow` from your `YunoConfig` and configure it in the CheckoutBuilder instead. + +### YunoConfig options + +Customization options: + +| Customization option | Description | +| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `saveCardEnabled` | Enables the Save card checkbox on card flows. Check the Save card section for more information. | +| `cardFormDeployed` | This option is only available for Full (Android). If `TRUE`, the system presents the card form deployed on the payment methods list. If `FALSE`, presents the normal card form on another screen. | +| `language` | Defines the language to be used in the payment forms. You can set it to one of the available language options: | +| `cardNumberPlaceholder` | This optional field allows you to customize the placeholder text for the card number field. Supports alphanumeric characters, spaces, and UTF-8 characters for localization. If not provided, the SDK uses the default placeholder ("Card number"). This customization does not affect card formatting, masking, BIN logic, or validation. | +| `hideCardholderName` | This optional field allows you to hide the cardholder name field in the card form. When set to `true`, the cardholder name field is not rendered. When not specified or set to `false`, the cardholder name field is displayed (default behavior). Hiding the field does not affect PAN, expiry, CVV collection, BIN logic, or 3DS/provider validations. The merchant is responsible for ensuring cardholder name is provided when required by their payment provider. | +| `styles` | Enables SDK-wide UI customization. Use it to define global visual styles like font family and button appearance (color, padding, radius, typography) through a `YunoStyles` object. For more information, check the styles section. | + +Update your manifest to use your application: + +```xml + +``` + +### Step 3: Create the checkout session + +Each payment requires a new `checkout_session`. Use the [Create checkout session](ref:create-checkout-session) endpoint to create one; use that session to initiate the payment. + +If your payment flow sends users to an external browser (e.g., for 3DS authentication or bank redirects), set the `callback_url` when creating your checkout session. See [Handle external browser return (callback_url)](#step-3-create-the-checkout-session) for details. + +### Step 4: Start the checkout process + +Call the `startCheckout` method inside the `onCreate()` function of the activity that initializes the SDK to start a new payment process with Full (Android): + +```kotlin +startCheckout( + checkoutSession: "checkout_session", + countryCode: "country_code_iso", + callbackPaymentState: ((String?) -> Unit)?, + merchantSessionId: String? = null +) +``` + +See [Parameters](#parameters). The following are the possible states returned by the `callbackPaymentState`: + +```kotlin +const val PAYMENT_STATE_SUCCEEDED = "SUCCEEDED" +const val PAYMENT_STATE_FAIL = "FAIL" +const val PAYMENT_STATE_PROCESSING = "PROCESSING" +const val PAYMENT_STATE_REJECT = "REJECT" +const val PAYMENT_STATE_INTERNAL_ERROR = "INTERNAL_ERROR" +const val PAYMENT_STATE_STATE_CANCELED_BY_USER = "CANCELED" +``` + +Possible states: + +| **State** | **Description** | **Additional action required** | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `SUCCEEDED` | The transaction or payment process was successfully completed without any errors. | No. | +| `FAIL` | The transaction failed due to errors such as data validation issues, server connection failures, or technical/network problems. | Yes. Investigate the cause of failure (validation, network, server) and take corrective measures. | +| `PROCESSING` | The transaction is currently in progress, awaiting approval or verification. | No. | +| `REJECT` | The transaction was rejected due to reasons like insufficient funds or suspected fraudulent activity. | Yes. Inform the user of the rejection, provide the reason if possible, and suggest actions. | +| `INTERNAL_ERROR` | An unexpected internal error occurred within the system handling the payment process. | Yes. Requires technical intervention to review the system, fix internal issues, and retry or inform the user. | +| `CANCELED` | The user voluntarily canceled the transaction or abandoned the payment process. | No. | + +#### Payment status validation + +This section explains how the SDK handles payment status when users cancel or leave payment flows, and how the SDK status relates to the backend payment status in these scenarios. + +##### Sync payment methods (Google Pay) + +For synchronous payment methods like Google Pay, when a user cancels or closes the wallet UI before a payment service provider (PSP) response is received: + +* **SDK Status**: Returns `CANCELED` (CANCELLED_BY_USER) +* **Backend payment status**: Remains `PENDING` until PSP timeout or merchant cancellation +* **Important**: The SDK will not return `REJECT` or `PROCESSING` in this scenario + +This ensures that the backend payment remains in a pending state and can be properly handled by the merchant's system. + +##### Async payment methods (PIX and QR-based methods) + +For asynchronous payment methods like PIX, when a user closes the QR code window (clicks X) before completing the payment: + +* **SDK Status**: Returns `PROCESSING`, optionally with a sub-status such as `CLOSED_BY_USER` +* **Backend payment status**: Remains `PENDING` and the QR code remains valid until expiry +* **Checkout session reuse**: Re-opening the same checkout session can display the same valid QR code +* **No Automatic Cancellation**: The PIX payment is not automatically cancelled when the user closes the QR window + +This behavior allows users to return to the payment flow and complete the transaction using the same QR code before it expires. + +##### Expired async payments + +If a PIX QR code expires naturally: + +* **Backend Status**: Updated to `EXPIRED` +* **SDK Status**: SDK callbacks and polling endpoints return `EXPIRED` consistently + +This ensures merchants receive accurate status information when a payment method has expired. + +### Step 5: Add the SDK view to the checkout + +Use the `PaymentMethodListViewComponent` to display the available payment methods when implementing Full (Android) with Jetpack Compose. This component provides callbacks to notify your app when to enable or disable the pay button, and when an enrolled payment method is successfully removed. + +#### Component signature + +```kotlin +@Composable +fun PaymentMethodListViewComponent( + activity: Activity, + modifier: Modifier? = null, + onPaymentSelected: (Boolean) -> Unit, + onUnEnrollSuccess: (Boolean) -> Unit = {} +) +``` + +#### Component options + +* `activity: Activity`: Current `Activity` where the component is hosted. Required for payment flows. +* `modifier: Modifier?` (optional): Layout and appearance (e.g. padding, spacing). Defaults to `null`. +* `onPaymentSelected: (Boolean) -> Unit`: Invoked when a payment method is selected or deselected (`true` = method selected, enable pay button; `false` = none selected). +* `onUnEnrollSuccess: (Boolean) -> Unit` (optional): Invoked when a stored payment method is successfully removed. + +#### Example + +```kotlin +val coroutineScope = rememberCoroutineScope() +val snackbarHostState = remember { SnackbarHostState() } +var paymentMethodIsSelected by remember { mutableStateOf(false) } + +Column( + modifier = Modifier + .weight(1f) + .verticalScroll(rememberScrollState()) +) { + PaymentMethodListViewComponent( + activity = activity, + onPaymentSelected = { isSelected -> + paymentMethodIsSelected = isSelected + }, + onUnEnrollSuccess = { success -> + if (success) { + coroutineScope.launch { + snackbarHostState.showSnackbar( + message = "Your payment method has been removed", + ) + } + } + }, + ) +} +``` + +> ❗ Important +> +> Always wrap the component in a `Column` with `.verticalScroll(rememberScrollState())`. Without this, the list of payment methods may not render or scroll properly when there are multiple methods available. + +### Step 6: Initiate the payment process + +Call the `startPayment()` method to start a payment process: + +```kotlin +startPayment( + showStatusYuno: Boolean, + callbackOTT: (String?) -> Unit = this::onTokenUpdated, + callBackTokenWithInformation: (OneTimeTokenModel?) -> Unit = this::onTokenComplete +) + +``` + +#### Options + +Configure the payment with the following options: + +| Parameter | Description | +| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `showStatusYuno` | A boolean that specifies whether the payment status should be displayed within the Yuno interface. | +| `callbackOTT` | A required function that returns the updated one-time token (OTT) needed to complete the payment process. This token is required to complete the payment. | +| `callBackTokenWithInformation` | A function that supplies detailed information about the one-time token, wrapped in a `OneTimeTokenModel` object, allowing for comprehensive handling of token details. | + +#### OneTimeTokenModel + +The `callBackTokenWithInformation` callback provides detailed information about the one-time token through the `OneTimeTokenModel` object: + +```kotlin +@Parcelize +data class OneTimeTokenModel( + val token: String? = null, + val vaultedToken: String? = null, + val vaultOnSuccess: Boolean? = null, + val type: String? = null, + val cardData: CardInformationModel? = null, + val customer: CustomerPayerInformationModel? = null, +) : Parcelable +``` + +**Card Information Model** + +```kotlin +@Parcelize +data class CardInformationModel( + val holderName: String? = null, + val iin: String? = null, + val lfd: String? = null, + val numberLength: Int? = null, + val securityCodeLength: Int? = null, + val brand: String? = null, + val type: String? = null, + val category: String? = null, + val issuerName: String? = null, + val issuerCode: String? = null, + val countryCode: String? = null, +) : Parcelable +``` + +**Customer Payer Information Model** + +```kotlin +`@Parcelize +data class CustomerPayerInformationModel( + val name: String? = null, + val lastName: String? = null, + val email: String? = null, + val document: Document? = null, + val phone: Phone? = null, + val address: Address? = null, + val deviceFingerPrint: String? = null, + val thirdPartySessionId: String? = null, +) : Parcelable +``` + +**Supporting Models** + +```kotlin +@Parcelize +data class Document( + val documentNumber: String? = null, + val documentType: String? = null, +) : Parcelable + +@Parcelize +data class Phone( + val number: String, + val countryCode: String, +) : Parcelable + +@Parcelize +data class Address( + val addressLine1: String? = null, + val addressLine2: String? = null, + val country: String? = null, + val city: String? = null, + val state: String? = null, + val zipCode: String? = null, + val neighborhood: String? = null, +) : Parcelable +``` + + + +### Step 7: Get the one-time token (OTT) + +After the customer fills out the requested data in Yuno's payment forms, you will obtain the one-time token, a required parameter to create a payment using the Yuno API. + +The one-time token will be shared by Yuno using the `callbackOTT` function you provided in Step 6 when initiating the payment. The one-time token will be available in the `onActivityResult`. + +A loader can be shown while the one-time token is generated. Use Yuno's default or implement your own with the required configuration. + +### Step 8: Create the payment + +After receiving the one-time token from [Step 7](#step-7-get-the-one-time-token-ott), create the payment using the [Create payment endpoint](https://docs.y.uno/reference/create-payment). Use the `checkout_session` from [Step 3](#step-3-create-the-checkout-session) and the one-time token to create the payment. + +The response from the Create payment endpoint will include the parameter `sdk_action_required`, which defines if additional actions are required to finish the payment based on the payment type. + +> 🚧 Continue Payment Method Integration +> +> Yuno **requires** you integrate the `continuePayment` method of the SDK after the payment is created because certain asynchronous payment methods require additional customer actions to complete. The API will inform you of this scenario via the `sdk_action_required` field of the response, which will be returned as true. The `yuno.continuePayment()` function will display additional screens to customers, where they can carry out the necessary actions to complete the payment without you needing to handle every scenario. + +### Step 9: Continue payment + +Yuno requires integrating the SDK's `continuePayment` method after the payment is created, as certain asynchronous payment methods require additional customer actions to complete. The response from the [Create payment endpoint](https://docs.y.uno/reference/create-payment), from Step 8, will include a `sdk_action_required` field. If it returns `TRUE`, you need to call the `continuePayment()` function to show additional screens that allow the customer to complete the payment. Otherwise, this step is not necessary. Call the `continuePayment` method: + +```kotlin +continuePayment( + showPaymentStatus: Boolean = true, + checkoutSession: String? = null, + countryCode: String? = null, + callbackPaymentState: ((String?) -> Unit)? = null +) +``` + +To show your payment status screens, send `FALSE` in the `showPaymentStatus` parameter. Then, get the payment state by callback. + +### Complementary features + +For styling, themes, form options, and additional configurations (including Click to Pay with Passkey), see [SDK customizations](android-customizations). + +## Common reference + +For full parameter and customization details, see the [Android SDK Common Reference](android-sdk-common-reference). diff --git a/docs/Yuno SDKs/ios-sdks/copy-of-payment-flows-1.md b/SDKs/Full Checkout/ios-payments.md similarity index 55% rename from docs/Yuno SDKs/ios-sdks/copy-of-payment-flows-1.md rename to SDKs/Full Checkout/ios-payments.md index 6bf908915..c379baa53 100644 --- a/docs/Yuno SDKs/ios-sdks/copy-of-payment-flows-1.md +++ b/SDKs/Full Checkout/ios-payments.md @@ -1,7 +1,7 @@ --- -title: Copy of Payment Flows +title: Payment Flows deprecated: false -hidden: true +hidden: false metadata: robots: index --- @@ -19,9 +19,7 @@ The iOS SDK makes it easy to integrate payment flows into your iOS app. * Active Yuno account; API credentials (obtain from the [Yuno Dashboard](https://dashboard.y.uno/) β†’ **Developers** > **Credentials**) * Create `checkout_session` and payment via the API; create a customer using the [Create customer endpoint](ref:create-customer) before creating a payment -## Include the library in your project - -The first step is always including the library in your project; this step is performed regardless of which integration type you choose. You can add the Yuno iOS SDK using CocoaPods or Swift Package Manager. +The first step is including the library in your project. You can add the Yuno iOS SDK using CocoaPods or Swift Package Manager. **Option 1: CocoaPods** @@ -47,17 +45,7 @@ dependencies: [ ] ``` -Once Step 1 is complete, continue with your desired integration. - -### Basic flows - -* [Full (iOS)](#full-ios): Complete control with backend support and full customization options -* [Seamless (payment iOS)](#seamless-payment-ios): Fastest integration with pre-built UI components - -### Advanced flows - -* [Lite (iOS)](#lite-ios): Lightweight integration allowing you to control the UI and payment methods list, as well as backend support -* [Headless (iOS)](#headless-ios): Full checkout experience customization without requiring PCI compliance +Once Step 1 is complete, continue with the Full Checkout integration. ## Parameters @@ -71,9 +59,9 @@ For the full list of parameters and YunoConfig, see the [iOS SDK Common Referenc | `viewController` | UIViewController that presents the payment flow. Required for delegate. | | `yunoCreatePayment(with:)` | Delegate: create payment on your backend with the one-time token. | | `yunoPaymentResult(_:)` | Delegate: payment finished. Receives `Yuno.Result` value (e.g., `.succeeded`, `.fail`, `.processing`). See [Payment Status reference](ref:payment) for status mapping. | -| `YunoConfig` (initialize) | Optional: appearance, saveCardEnabled, keepLoader. See Common Reference. | +| `YunoConfig` (initialize) | Optional: appearance, saveCardEnabled, keepLoader, hideCardholderName, cardNumberPlaceholder. See Common Reference. | -## Full (iOS) +## Full Checkout Implement the Full iOS SDK: complete payment solution with automatic payment method display and minimal UI customization. See [Requirements](#requirements) above. @@ -104,6 +92,8 @@ struct YunoConfig { var appearance: Appearance? = nil var saveCardEnabled: Bool = false var keepLoader: Bool = false + var hideCardholderName: Bool = false + var cardNumberPlaceholder: String? = nil } ``` @@ -116,6 +106,8 @@ Customization options: | `appearance` | Enables SDK-wide UI customization. Use it to define global visual styles like colors, fonts, and button appearance. For more information, check the SDK customizations page. | | `saveCardEnabled` | Enables the Save card checkbox on card flows. Check the Save card section for more information. | | `keepLoader` | Controls loader display behavior. When `true`, the loader remains visible until manually hidden. | +| `hideCardholderName` | When set to `true`, hides the cardholder name field in the card form. Default is `false`. Hiding the field does not affect PAN, expiry, CVV collection, BIN logic, or 3DS/provider validations. The merchant is responsible for ensuring cardholder name is provided when required by their payment provider. | +| `cardNumberPlaceholder` | This optional field allows you to customize the placeholder text for the card number field. Supports alphanumeric characters, spaces, and UTF-8 characters for localization. If not provided, the SDK uses the default placeholder ("Card number"). This customization does not affect card formatting, masking, BIN logic, or validation. | | `language` | Defines the language to be used in the payment forms. You can set it to one of the available language options: `en` (English), `es` (Spanish), `pt` (Portuguese), `fil` (Filipino), `id` (Indonesian), `ms` (Malay), `th` (Thai), `zh-TW` (Chinese Traditional), `zh-CN` (Chinese Simplified), `vi` (Vietnamese), `fr` (French), `pl` (Polish), `it` (Italian), `de` (German), `ru` (Russian), `tr` (Turkish), `nl` (Dutch), `sv` (Swedish), `ko` (Korean), `ja` (Japanese). | ### Step 3: Create the checkout session @@ -412,371 +404,6 @@ This ensures merchants receive accurate status information when a payment method For styling, themes, form options, and additional configurations, see [SDK customizations](ios-customizations). -## Seamless (payment iOS) - -Seamless (payment iOS) for payments. - -**Recommended**: Use Seamless (payment iOS) for pre-built UI and customization. - -This SDK is ideal for merchants who: - -* Want control over the payment flow while leveraging pre-built UI components -* Need to customize the payment experience while maintaining PCI compliance -* Require a balance between implementation speed and customization - -Seamless (payment iOS) includes features like: - -* Pre-built payment UI components with customization options -* Multiple payment method support -* Advanced payment status handling -* Comprehensive error management - -For merchants requiring complete UI control or more advanced features, consider using our [Full](#full-ios) instead. - -See [Requirements](#requirements) above. - -### Step 1: Create a customer - -Create a customer using the [Create customer endpoint](ref:create-customer) before initiating payments. This step is required to: - -* Identify the person making the payment -* Enable saved card functionality (if enabled) -* Track payment history - -The customer ID returned from this endpoint will be used when creating the `checkout_session`. - -### Step 2: Create a checkout session - -Create a new `checkout_session` using the [Create checkout session](ref:create-checkout-session) endpoint to initialize the payment flow. Make sure to: - -* Include the customer ID obtained from the previous step -* Store the returned `checkout_session` ID for use in Step 6 of the integration -* Set `workflow` to `SDK_SEAMLESS` when creating the checkout session - - - ### **Auth vs capture** - - Control auth vs capture by sending `payment_method.detail.card.capture` in the checkout session: `false` = authorize only, `true` = capture immediately. - - -#### Checkout session options - -| Parameter | Required | Description | -| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `amount` | Yes | The primary transaction amount object containing `currency` (ISO 4217 code) and `value` (numeric amount in that currency). | -| `alternative_amount` | No | An alternative currency representation of the transaction amount with the same structure as `amount` (`currency` and `value`). Useful for multi-currency scenarios, such as displaying prices to customers in their preferred currency (e.g., USD) while processing the payment in the local currency (e.g., COP). | -| `workflow` | Yes | Set to `SDK_SEAMLESS` for Seamless (payment iOS) integration. | - -> 🚧 Checkout session usage -> -> The `checkout_session` is unique for each payment attempt and cannot be reused. - -Follow the steps in [Include the library in your project](#include-the-library-in-your-project) above. - -### Step 3: Initialize SDK - -Retrieve your public API keys from the [Yuno Dashboard](https://dashboard.y.uno/). - -```swift -import YunoSDK - -Yuno.initialize( - apiKey: "PUBLIC_API_KEY", - config: YunoConfig(), - callback: { (value: Bool) in } -) -``` - -Configure the Seamless checkout using `YunoConfig` (for card form type, appearance, save card, and loader behavior). - -Use the `YunoConfig` data class to set additional configurations. Options: - -| Option | Description | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **saveCardEnabled** | Enables the save card checkbox for card flows. Check the Save card section for more information. | -| **language** | Defines the language to be used in the payment forms. You can set it to one of the available language options: `en`, `es`, `pt`, `fil`, `id`, `ms`, `th`, `zh-TW`, `zh-CN`, `vi`, `fr`, `pl`, `it`, `de`, `ru`, `tr`, `nl`, `sv`, `ko`, `ja`. | -| **appearance** | Enables SDK-wide UI customization. Use it to define global visual styles like colors, fonts, and button appearance. For more information, check the SDK customizations page. | - -### Step 4: Implement the payment delegate - -Create a class that adopts the `YunoPaymentDelegate` protocol as described in the Full (iOS) section. - -### Step 5: Start the checkout and payment process - -Use `Yuno.startPaymentSeamlessLite` from your `ViewController` to start the seamless checkout UI: - -```swift -let seamlessParams = SeamlessParams( - checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638", - countryCode: "BR", - language: "en", - viewController: self -) - -let paymentSelected = PaymentMethodSelected( - paymentMethodType: "CARD", - vaultedToken: nil -) - -// Using async/await -let result = await Yuno.startPaymentSeamlessLite( - with: seamlessParams, - paymentSelected: paymentSelected, - showPaymentStatus: true -) - -// Or using callbacks -Yuno.startPaymentSeamlessLite( - with: seamlessParams, - paymentSelected: paymentSelected, - showPaymentStatus: true, - callback: { result in - // Handle result - } -) -``` - -#### Options - -| Parameter | Description | -| :------------------ | :---------------------------------------------------------------------------------------------------- | -| `seamlessParams` | Configuration object containing `checkoutSession`, `countryCode`, `language`, and `viewController`. | -| `paymentSelected` | Specifies the payment method, either through a vaulted token or a selected payment type. | -| `showPaymentStatus` | When `true`, displays the SDK's default result screen. When `false`, handle status through callbacks. | - -Seamless (payment iOS) automatically handles payment creation on the backend. You still receive the payment result through the callback or return value, but you don't need to call the Create Payment API manually. - -### Step 6: Handle payment result - -The SDK returns the payment result through the callback or return value. Handle it as described in the Full (iOS) section. - -### Complementary features - -For styling, themes, form options, and additional configurations, see [SDK customizations](ios-customizations). - -## Lite (iOS) - -Lite (iOS) for payments. - -**Recommended**: Use the [Seamless](#seamless-payment-ios) for pre-built UI; use Lite for a streamlined card-focused integration. - -This SDK offers a streamlined integration process with essential payment functionality, making it ideal for merchants who: - -* Need a quick implementation with minimal customization requirements -* Want to focus primarily on card payment processing -* Prefer a ready-to-use UI that handles the payment flow - -Lite (iOS) includes core features like: - -* Pre-built payment UI components -* Card payment processing -* Basic payment status handling -* Essential error management - -For merchants requiring more advanced features like multiple payment methods, custom UI, or advanced fraud prevention, consider using our [Full](#full-ios) instead. - -See [Requirements](#requirements) above. - -### Step 1: Create a customer - -Create a customer using the [Create customer endpoint](ref:create-customer) before initiating payments. This step is required to: - -* Identify the person making the payment -* Enable saved card functionality (if enabled) -* Track payment history - -The customer ID returned from this endpoint will be used when creating the `checkout_session`. - -### Step 2: Create a checkout session - -Create a new `checkout_session` using the [Create checkout session](ref:create-checkout-session) endpoint to initialize the payment flow. Make sure to: - -* Include the customer ID obtained from the previous step -* Store the returned `checkout_session` ID for use in later steps -* Remember that the `checkout_session` is unique for each payment attempt and cannot be reused - -If your payment flow sends users to an external browser (e.g., for 3DS authentication or bank redirects), set the `callback_url` when creating your checkout session. See [Handle external browser return](#step-6-handle-external-browser-return-optional) for details. - -Follow the steps in [Include the library in your project](#include-the-library-in-your-project) above. - -### Step 3: Initialize SDK with the public key - -Initialize the SDK: - -1. Get your public API keys from the [Yuno Dashboard](https://dashboard.y.uno/) -2. Initialize the SDK by calling `Yuno.initialize()` with your API key and configuration: - -```swift -import YunoSDK - -Yuno.initialize( - apiKey: "PUBLIC_API_KEY", - config: YunoConfig(), - callback: { (value: Bool) in } -) -``` - -Use `YunoConfig` to configure `appearance`, `saveCardEnabled`, and `keepLoader`. - -### Step 4: Implement the payment delegate - -Create a `ViewController` that adopts `YunoPaymentDelegate` as described in the Full (iOS) section. - -### Step 5: Start the Lite checkout process - -After initializing the SDK and creating the checkout session, start the payment process using Lite (iOS). Fetch available payment methods from the API, display them in your UI, then mount the selected method. - -**Step 1: Fetch available payment methods** - -Call the API to retrieve payment methods available for the checkout session: - -```swift -// Backend API call -GET /v1/checkout/sessions/{checkout_session}/payment-methods -``` - -**Step 2: Display payment methods in your UI** - -Present the payment methods to your customer and capture their selection. - -**Step 3: Mount the selected payment method** - -```swift -let paymentSelected = PaymentMethodSelected( - paymentMethodType: "CARD", // User's selection - vaultedToken: nil // Optional: for enrolled methods -) - -Yuno.startPaymentLite( - with: self, - paymentSelected: paymentSelected, - showPaymentStatus: true -) -``` - -The payment starts automatically when you call `startPaymentLite()`. - -A loader can be shown while the one-time token is generated. Use Yuno's default or implement your own with the required configuration. - -### Step 6: Create the payment - -After receiving the one-time token from Lite (iOS), create the payment using the [Create payment endpoint](https://docs.y.uno/reference/create-payment). Use the `checkout_session` from the previous steps and the one-time token to create the payment. - -The response from the Create payment endpoint will include the parameter `sdk_action_required`, which defines if additional actions are required to finish the payment based on the payment type. If `sdk_action_required` is `true`, you must call `continuePayment()` to complete the flow. - -## Headless (iOS) - -Yuno Headless iOS SDK for payments. - -**Recommended**: Use the [Seamless](#seamless-payment-ios) for pre-built UI; use Headless for maximum customization and UI control. - -Yuno's Headless iOS SDK lets you create payments and enroll payment methods without relying on pre-built UI. - -Headless (iOS) is ideal for merchants who: - -* Need full control over the payment UI and user experience -* Want to build custom payment flows -* Require advanced integration capabilities - -Headless (iOS) includes core features like: - -* Direct API access for payment processing -* Token generation for payment methods -* 3DS authentication handling -* Fraud prevention data collection - -For merchants preferring a pre-built UI solution, consider using our [Full](#full-ios) or [Lite](#lite-ios) instead. - -See [Requirements](#requirements) above. - -### Step 1: Create a customer - -Create a customer using the [Create customer endpoint](ref:create-customer) before initiating payments. This step is required to: - -* Identify the person making the payment -* Enable saved payment method functionality (if enabled) -* Track payment history - -The customer ID returned from this endpoint will be used when creating the `checkout_session`. - -### Step 2: Create a checkout session - -Create a new `checkout_session` using the [Create checkout session](ref:create-checkout-session) endpoint to initialize the payment flow. Make sure to: - -* Include the customer ID obtained from the previous step -* Store the returned `checkout_session` ID for use in later steps - -The `checkout_session` is unique for each payment attempt and cannot be reused. - -Follow the steps in [Include the library in your project](#include-the-library-in-your-project) above. - -### Step 3: Initialize Headless with the public key - -```swift -import YunoSDK - -Yuno.initialize( - apiKey: "PUBLIC_API_KEY" -) -``` - -### Step 4: Start the checkout process - -Use `Yuno.apiClientPayment` to configure a headless checkout client: - -```swift -var apiClientPayment: YunoPaymentHeadless? - -apiClientPayment = Yuno.apiClientPayment( - countryCode: "CO", - checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638" -) -``` - -Then use `apiClientPayment.generateToken(...)` to generate one-time tokens: - -```swift -// Step 1: Collect payment information in your custom UI - -// Step 2: Generate token with card data -let tokenCollectedData = TokenCollectedData( - checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638", - paymentMethod: CollectedData( - type: "CARD", - vaultedToken: nil, - card: CardData( - save: true, - detail: CardData.Detail( - number: "4111111111111111", - expirationMonth: 12, - expirationYear: 25, - securityCode: "123", - holderName: "Andrea", - type: .credit - ) - ), - customer: Customer() - ) -) - -do { - let result = try await apiClientPayment.generateToken(data: tokenCollectedData) - // Extract token from result and create payment - if let token = result["token"] as? String { - // Call Create Payment API on your backend - } -} catch { - print("Token generation failed: \(error)") -} -``` - -After generating the token, create the payment on your backend using the [Create Payment endpoint](https://docs.y.uno/reference/create-payment), then handle 3DS challenges and continue payments as needed. - -**When to use Headless:** - -* You need complete control over the entire payment UI -* You have specific design requirements that can't be met with SDK components -* You're building a highly customized checkout experience ## Common reference diff --git a/SDKs/Full Checkout/web-payments.md b/SDKs/Full Checkout/web-payments.md new file mode 100644 index 000000000..00fd9c509 --- /dev/null +++ b/SDKs/Full Checkout/web-payments.md @@ -0,0 +1,205 @@ +--- +title: Payment Flows +deprecated: false +hidden: false +metadata: + robots: index +--- +The Web SDK makes it easy to integrate payment flows into your web and browser-based experiences. + +## Additional resources + +* Yuno offers a [TypeScript library](https://www.npmjs.com/package/@yuno-payments/sdk-web-types) that complements the SDK. +* See [Choose the right integration for you](choose-your-integration) if you're unsure which flow to follow. +* See the [Demo App](https://github.com/yuno-payments/yuno-sdk-web) for a complete implementation (clone from the repository). + +## Requirements + +* A [customer](ref:create-customer) created in Yuno and a [checkout session](ref:create-checkout-session): reference each API when setting up your backend. +* Public API key (obtain from the [Yuno Dashboard](https://dashboard.y.uno/) β†’ **Developers** > **Credentials**) + +The first step is including the library in your project. The integration guide provides three flexible methods: + +1. **Direct HTML script inclusion**: Add the script tag to your page. +2. **Dynamic JavaScript injection**: Load the SDK at runtime. +3. **NPM module installation**: Install via npm (recommended). + +**Option 1: NPM (Recommended)** + +```bash +npm install @yuno-payments/sdk-web +``` + +**Option 2: HTML Script Tag** + +```html + +``` + +**Option 3: Dynamic JavaScript** + +```javascript +const script = document.createElement('script'); +script.src = 'https://sdk-web.y.uno/v1.5/main.js'; +document.head.appendChild(script); +``` + +Once Step 1 is complete, continue with the Full Checkout integration. + +## Parameters + +These are the parameters covered in this guide. For the full list of parameters and callbacks, see the [Web SDK Common Reference](web-sdk-common-reference). + +| Parameter | Description | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `checkoutSession` | Checkout session ID from your backend (Create checkout session API). Required for all flows. | +| `elementSelector` | CSS selector for the element where the SDK mounts (e.g. `#root`). | +| `countryCode` | ISO country code where the payment runs (e.g. `FR`, `US`). | +| `language` | Language code for the UI (e.g. `fr-FR`). Optional; defaults to browser language when available. | +| `showLoading` | Show SDK loading spinner. Optional. | +| `showPaymentStatus` | Show payment result screen. Optional. | +| `yunoCreatePayment(oneTimeToken)` | Callback: send one-time token to your backend to create the payment; then call `yuno.continuePayment()`. | +| `yunoPaymentResult(status)` | Callback: payment finished. Receives [payment status](ref:payment) (e.g. `SUCCEEDED`, `DECLINED`, `PENDING`). | +| `yunoError(message, data)` | Callback: error during the flow. | +| `onLoading` | Callback: loading state updates. | +| `card` | Card form options (e.g. `onChange`, `isCreditCardProcessingOnly`). Optional. | + +## Full Checkout + +Implement Yuno's Full integration: pre-built checkout UI with full control over branding, forms, and flow. Use this when you want Yuno to render the checkout experience while you manage customer and checkout session creation on your backend. + +### Step 1: Include the library in your project + +Follow the steps in [Include the library in your project](#include-the-library-in-your-project) above. + +### Step 2: Initialize the SDK + +After including the library ([step 1](#step-1-include-the-library-in-your-project)), initialize the SDK. See [Quickstart guide](quickstart-guide#web-sdk-integration) for initialization. + +### Step 3: Start the checkout process + +Use the `yuno.startCheckout` function to start the checkout process with the necessary parameters. + +See [Parameters](#parameters) for all options. For styling, themes, and additional configurations, see [SDK customizations](sdk-customizations-web). + +```javascript +yuno.startCheckout({ + checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638", + elementSelector: "#root", + countryCode: "FR", + language: "fr-FR", + showLoading: true, + issuersFormEnable: true, + showPaymentStatus: true, + card: { + isCreditCardProcessingOnly: true, + onChange: ({ error, data }) => { + if (error) { + console.log('Card form error:', error); + } else { + console.log('Card form data:', data); + } + }, + }, + onLoading: (args) => { + console.log(args); + }, + yunoPaymentMethodSelected: () => { + console.log("Payment method selected"); + }, + yunoPaymentResult: (status) => { + console.log("Payment result:", status); + }, + yunoError: (message, data) => { + console.error("Payment error:", message, data); + }, + async yunoCreatePayment(oneTimeToken) { + await createPayment({ oneTimeToken, checkoutSession }); + yuno.continuePayment({ showPaymentStatus: true }); + }, +}); +``` + +By default, Yuno SDK renders as a modal. You can specify the element where the SDK will render. See [Render mode](#render-mode) for details. + +For all APMs (Google Pay, Apple Pay, PayPal), `onPaymentMethodSelected` triggers when the customer chooses the payment method (before the payment flow begins). Define `onPaymentMethodSelected` in `startCheckout` before `mountCheckout`. For PayPal, the payment sheet opens immediately after selectionβ€”no extra confirmation click required. + +### Step 4: Mount the SDK + +Display the payment methods: + +```javascript +yuno.mountCheckout(); +``` + +Alternatively, mount with a default payment method selected: + +```javascript +yuno.mountCheckout({ + paymentMethodType: PAYMENT_METHOD_TYPE, + vaultedToken: VAULTED_TOKEN, +}); +``` + +### Step 5: Initiate the payment process + +Call `yuno.startPayment()` to initiate the payment flow after the user selects a payment method: + +```javascript +const PayButton = document.querySelector("#button-pay"); + +PayButton.addEventListener("click", () => { + yuno.startPayment(); +}); +``` + +### Step 6: Get the OTT (one-time token) + +After the customer fills out the requested data in Yuno's payment forms, the SDK provides the one-time token. The configuration function `yunoCreatePayment(oneTimeToken)` is then triggered with the one-time token. + +```javascript +yunoCreatePayment(oneTimeToken); +``` + +You can also use `tokenWithInformation` to receive additional information provided by the customer in the checkout, such as installments or document type/number: + +```javascript +yunoCreatePayment(oneTimeToken, tokenWithInformation); +``` + +Use Yuno's default loader or implement your own with the required configuration. + +### Step 7: Create the payment + +Create a payment using the [Create Payment endpoint](https://docs.y.uno/reference/create-payment). The merchant's backend should call this endpoint to create the payment in Yuno using the one-time token and checkout session. + +After Step 6, the basic payment flow is implemented. Test using the checkout session and one-time token. For additional features, see [Complementary features](#complementary-features). + +**Required**: After creating a payment, integrate the `continuePayment` method. When the API response sets `sdk_action_required` to `true`, call `yuno.continuePayment()` to present the necessary screens. + +### `continuePayment` return value or null + +For payment methods that require merchant-side action (e.g., when the payment provider requires a redirect URL in a webview), the `await yuno.continuePayment()` method returns either an object with the following structure or null: + +```typescript +{ + action: 'REDIRECT_URL' + type: string + redirect: { + init_url: string + success_url: string + error_url: string + } +} | null +``` + +When the method returns an object, you can handle your application's payment flows that require custom redirect handling. When it returns null, no additional merchant-side action is needed. + +### Complementary features + +For styling, themes, form options, and additional configurations, see [SDK customizations](sdk-customizations-web). [Changelog](https://docs.y.uno/changelog/web-sdk-v13-changelog). + + +## Common reference + +For full parameter and customization details, see the [Web SDK Common Reference](web-sdk-common-reference). diff --git a/SDKs/Overview/References/_order.yaml b/SDKs/Overview/References/_order.yaml new file mode 100644 index 000000000..635ee9ce6 --- /dev/null +++ b/SDKs/Overview/References/_order.yaml @@ -0,0 +1,3 @@ +- web +- android +- ios diff --git a/SDKs/Overview/References/android.md b/SDKs/Overview/References/android.md new file mode 100644 index 000000000..bb0650505 --- /dev/null +++ b/SDKs/Overview/References/android.md @@ -0,0 +1,57 @@ +--- +title: Android SDK Common Reference +deprecated: false +hidden: false +metadata: + robots: index +--- + +Parameters, customizations, and advanced features for all Android SDK flows. Setup: [Payment flows (Android)](payment-flows-android), [Enrollment flows (Android)](enrollment-flows-android), [integration modes](choose-your-integration). + +## Key parameters (checkout session creation) + +When creating a checkout session on your backend for payment flows, the following parameters are commonly used across Android SDKs: + +| Parameter | Required | Description | +| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `amount` | Yes | The primary transaction amount object containing `currency` (ISO 4217 code) and `value` (numeric amount in that currency). | +| `alternative_amount` | No | An alternative currency representation of the transaction amount with the same structure as `amount` (`currency` and `value`). Useful for multi-currency scenarios, such as displaying prices to customers in their preferred currency (e.g., USD) while processing the payment in the local currency (e.g., COP). | + +## Payment parameters (full reference) + +Parameters for payment flows. All parameters used in [Payment flows (Android)](payment-flows-android) are listed here with full detail. + +| Parameter | Type | Required | Description | +| ----------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `checkoutSession` | string | Yes | Checkout session ID from your backend (Create checkout session API). Required for all payment flows. | +| `countryCode` | string | Yes | ISO country code where the payment runs (e.g. `US`, `BR`). Determines available payment methods and compliance. | +| `callbackPaymentState`| function | No | Callback invoked when the payment state changes. Receives the current state: e.g. `SUCCEEDED`, `FAIL`, `PROCESSING`, `REJECT`. Use for UI updates, analytics, or navigation. | +| `merchantSessionId` | string | No | Optional merchant session identifier. Use to correlate the SDK session with your own session or order ID. | + +## YunoConfig options (initialize) + +Runtime behavior and appearance are configured via the `YunoConfig` data class when calling `Yuno.initialize(context, publicApiKey, config)`. All parameters used across Android payment and enrollment flows are listed below. For visual styling (fonts, colors, buttons), see [SDK customizations (Android)](android-customizations). + +| Parameter | Type | Required | Description | +| ------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `saveCardEnabled` | boolean | No | When `true`, allows the user to save or enroll the card during payment. Requires backend support for vaulting (e.g. `payment_method.vault_on_success` in checkout session). | +| `cardFormDeployed` | boolean | No | When `true`, the card form is deployed in a specific way (e.g. embedded vs modal). Behavior may vary by SDK version. | +| `language` | string | No | Language code for the SDK UI (e.g. `en`, `es`). Use a code from [Supported languages](languages-supported) when available. | +| `styles` | object | No | Custom styles applied to SDK UI elements. Define in your app's styles and reference here, or use theme overrides. See [SDK customizations (Android)](android-customizations) for font, button, and color options. | +| `placeholders` | object | No | Custom placeholder text for form fields (e.g. card number, cardholder name). Keys depend on SDK version. | + +## Enrollment parameters (full reference) + +Parameters for enrollment flows. All parameters used in [Enrollment flows (Android)](enrollment-flows-android) are listed here with full detail. + +| Parameter | Type | Required | Description | +| ------------------------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `customerSession` | string | Yes | Customer session ID from Create customer session API. Required. Associates the enrolled payment method with a specific customer. | +| `countryCode` | string | Yes | ISO country code (e.g. `US`, `BR`). Required for enrollment. | +| `showEnrollmentStatus` | boolean | No | When `true`, shows the enrollment result screen after the flow. Default `true`. Set to `false` to handle result only via callback. | +| `callbackEnrollmentState`| function | No | Callback invoked when enrollment state changes. Requires registering `initEnrollment` in your Activity's `onCreate` (or equivalent) so the SDK can deliver results. Optional when using `onActivityResult` with `requestCode`. | +| `requestCode` | int | No | Optional request code used when capturing the enrollment result via `onActivityResult`. Use when you prefer activity-result flow over callbacks. | + +## Enrolling payment methods + +You can enroll payment methods (store cards for future use) during the payment flow or via dedicated enrollment flows. For payment flows, enable save card in `YunoConfig` and set `payment_method.vault_on_success` (or equivalent) when creating the checkout session where supported. For dedicated enrollment, see [Enrollment flows (Android)](enrollment-flows-android). diff --git a/SDKs/Overview/References/ios.md b/SDKs/Overview/References/ios.md new file mode 100644 index 000000000..927fedb6e --- /dev/null +++ b/SDKs/Overview/References/ios.md @@ -0,0 +1,59 @@ +--- +title: iOS SDK Common Reference +deprecated: false +hidden: false +metadata: + robots: index +--- +Parameters, customizations, and advanced features for all Yuno iOS SDK flows. For integration setup, see [Payment flows (iOS)](payment-flows-ios), [Enrollment flows (iOS)](enrollment-flows-ios), and [integration modes](choose-your-integration). + +## Key parameters (checkout session creation) + +When creating a checkout session on your backend for payment flows, the following parameters are commonly used across iOS SDKs: + +| Parameter | Required | Description | +| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `amount` | Yes | The primary transaction amount object containing `currency` (ISO 4217 code) and `value` (numeric amount in that currency). | +| `alternative_amount` | No | An alternative currency representation of the transaction amount with the same structure as `amount` (`currency` and `value`). Useful for multi-currency scenarios, such as displaying prices to customers in their preferred currency (e.g., USD) while processing the payment in the local currency (e.g., COP). | + +## Payment parameters (full reference) + +Parameters for payment flows. All parameters used in [Payment flows (iOS)](payment-flows-ios) are listed here with full detail. + +| Parameter | Type | Required | Description | +| -------------------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `checkoutSession` | string | Yes | Checkout session ID from your backend (Create checkout session API). Required for all payment flows. | +| `countryCode` | string | Yes | ISO country code where the payment runs (e.g. `BR`, `US`). Determines available payment methods and compliance. | +| `language` | string | No | Language code for the SDK UI (e.g. `en`, `pt-BR`). Optional. See [Supported languages](languages-supported) when available. | +| `viewController` | UIViewController | Yes* | The view controller that presents the payment flow. The SDK uses it to present modals and capture result. | +| `yunoCreatePayment(with:)` | delegate | Yes | Delegate method: create the payment on your backend using the one-time token provided by the SDK. After creating the payment via the API, inform the SDK so it can continue the flow. | +| `yunoPaymentResult(_:)` | delegate | No | Delegate method: invoked when the payment flow finishes. Receives a `Yuno.Result` enum value (`.succeeded`, `.fail`, `.processing`, `.reject`, `.userCancelled`, `.internalError`). These values map to [payment statuses](ref:payment). Use for UI updates or navigation. | + +## YunoConfig options (initialize) + +Runtime behavior and appearance are configured via `YunoConfig` when calling `Yuno.initialize(apiKey:config:)`. All parameters used across iOS payment and enrollment flows are listed below. For visual styling (fonts, colors, buttons), see [SDK customizations (iOS)](ios-customizations). + +| Parameter | Type | Required | Description | +| ----------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `appearance` | Appearance | No | Custom appearance (fonts, colors, buttons). Use `Yuno.Appearance(...)` to set `fontFamily`, `accentColor`, `buttonBackgroundColor`, `buttonTitleColor`, and related fields. See [SDK customizations (iOS)](ios-customizations) for all options. | +| `saveCardEnabled` | boolean | No | When `true`, allows the user to save or enroll the card during payment. Requires backend support for vaulting. | +| `keepLoader` | boolean | No | When `true`, keeps the loader visible until explicitly dismissed or until the flow completes. Use to control loading UX. | +| `hideCardholderName` | boolean | No | When `true`, hides the cardholder name field in the card form. Default `false`. | +| `cardNumberPlaceholder` | string | No | Placeholder text for the card number field. If not set, the SDK uses a default. Does not affect formatting or validation. | + +## Enrollment parameters (full reference) + +Parameters for enrollment flows. All parameters used in [Enrollment flows (iOS)](enrollment-flows-ios) are listed here with full detail. + +| Parameter | Type | Required | Description | +| -------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `customerSession` | string | Yes | Customer session ID from Create customer session API. Required. Associates the enrolled payment method with a specific customer. | +| `countryCode` | string | Yes | ISO country code (e.g. `BR`, `US`). Required for enrollment. | +| `language` | string | No | Language code for the SDK UI. Optional. | +| `viewController` | UIViewController | Yes* | The view controller that presents the enrollment flow. Required for delegate-based enrollment. | +| `yunoEnrollmentResult(_:)` | delegate | No | Delegate method: invoked when enrollment finishes. Receives the result (e.g. vaulted token, status). Use for UI updates or navigation. | +| `YunoConfig` | YunoConfig | No | Same options as payment (e.g. `appearance`, `saveCardEnabled`, `keepLoader`, `hideCardholderName`). See [YunoConfig options (initialize)](#yunoconfig-options-initialize) above. | + +## Enrolling payment methods + +You can enroll payment methods (store cards for future use) during the payment flow or via dedicated enrollment flows. For payment flows, enable save card in `YunoConfig` and set `payment_method.vault_on_success` (or equivalent) when creating the checkout session where supported. For dedicated enrollment, see [Enrollment flows (iOS)](enrollment-flows-ios). diff --git a/SDKs/Overview/References/web.md b/SDKs/Overview/References/web.md new file mode 100644 index 000000000..b5379a38e --- /dev/null +++ b/SDKs/Overview/References/web.md @@ -0,0 +1,210 @@ +--- +title: Web SDK Common Reference +deprecated: false +hidden: false +metadata: + robots: index +--- +Parameters, customizations, and advanced features for all Web SDK flows. See [Quickstart guide](quickstart-guide#web-sdk-integration) and [Choose the Right Integration for You](choose-your-integration) for introductory information. + +## TypeScript support + +TypeScript: Yuno provides a [TypeScript library](https://www.npmjs.com/package/@yuno-payments/sdk-web-types) for all available methods. + +## Subresource Integrity (SRI) + +This browser security feature lets you ensure a loaded script has not been tampered with. You provide a cryptographic hash alongside the script URL; the browser verifies the downloaded bytes match the declared hash before executing the code. + +* **Integrity**: Guarantees the exact code built and published is what runs in the browser. +* **Immutability**: When paired with full semantic version URLs, it ensures stable, reproducible integrations. +* **Defense-in-depth**: Mitigates risks from supply-chain or transport-layer compromise. + +### URL formats + +When implementing SRI, use the full semantic version URL format to ensure immutable, tamper-evident integrations. + +* **Full (immutable) URL with SRI**: Full semantic version path used for locked, tamper-evident integrations with an SRI hash. +* **Partial (mutable) URL**: Version with major and minor (e.g., v1.5).Β  This version will receive patch improvements.Β  This is useful if you like to avoid updates in your code base. + +### How to integrate the SDK with SRI + +Replace `src` and `integrity` with the environment/version you target. `crossorigin="anonymous"` lets the browser validate the SRI for cross-origin scripts. + +The hash can be found in the manifest.json file at `files.["main.js"].integrity`. + +```html + +``` + +`src`for production is `https://sdk-web.y.uno/versions-sri.json` . + +### Using NPM package + +```javascript +import { loadScript } from '@yuno-payments/sdk-web' + +const yuno = await loadScript({ + sri: true +}) +``` + +### Validation notes + +* Open DevTools Network tab and confirm main.js returns `200` from the full-version path. +* Verify the response headers allow cross-origin fetches for static assets if served from a distinct origin (`crossorigin="anonymous"` is set). +* Ensure the integrity attribute exactly matches the generated hash, including the sha384- prefix. +* Any change to main.js changes the hash. When changing versions, always regenerate or retrieve the new sha384 value and update the integrity attribute. + +### SRI Troubleshooting + +* Hash mismatchs cause the script to fail execution with an integrity error (e.g., you updated the file but not the hash). To fix, rebuild, retrieve the new sha384 from sri-manifest.json, and update integrity. + +* Browser blocks SRI on cross-origin request when the crossorigin attribute is missing or CORS is restrictive. To fix, add `crossorigin="anonymous"` and configure the static hosting to allow cross-origin fetches for JS assets. + +## Key parameters (checkout session creation) + +When creating a checkout session on your backend, the following parameters are commonly used across web SDKs: + +| Parameter | Required | Description | +| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `amount` | Yes | The primary transaction amount object containing `currency` (ISO 4217 code) and `value` (numeric amount in that currency). | +| `alternative_amount` | No | An alternative currency representation of the transaction amount with the same structure as `amount` (`currency` and `value`). Useful for multi-currency scenarios, such as displaying prices to customers in their preferred currency (e.g., USD) while processing the payment in the local currency (e.g., COP). | + +## Payment and checkout parameters (full reference) + +Parameters for `yuno.startCheckout`, `yuno.mountCheckout`, and related payment flows. All parameters used in [Payment flows (Web)](payment-flows-web) are listed here with full detail. + +### Core parameters + +| Parameter | Type | Required | Description | +| ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `checkoutSession` | string | Yes | Checkout session ID returned from your backend (Create checkout session API). Required for all payment flows. | +| `elementSelector` | string | No* | CSS selector for the element where the SDK mounts (e.g. `#root`). Deprecated when used alone; prefer `renderMode.elementSelector` object to control APM and action areas independently. *Required when `renderMode.type` is `'element'` and using the object form. | +| `countryCode` | string | Yes | ISO country code where the payment runs (e.g. `FR`, `US`). Determines available payment methods and compliance. | +| `language` | string | No | Language code for the UI (e.g. `fr-FR`, `en-US`). Defaults to browser language when available. See [Supported languages](languages-supported). | +| `showLoading` | boolean | No | When `true`, shows the SDK loading spinner. Default `true`. Remains visible until `hideLoader()` or `continuePayment()` is called. | +| `showPaymentStatus` | boolean | No | When `true`, shows the payment result screen after the flow completes. Optional. | +| `issuersFormEnable` | boolean | No | When `true`, shows the issuer (bank) list form. Default `true` in source. Optional. | + +### Callbacks + +| Parameter | Type | Required | Description | +| --------------------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `yunoCreatePayment(oneTimeToken)` | function | Yes | Callback invoked when the user completes the card/APM step. Receive the one-time token; send it to your backend to create the payment via the API; then call `yuno.continuePayment()` to resume the flow. | +| `yunoPaymentResult(status)` | function | No | Callback invoked when the payment flow finishes. Receives the [payment status](ref:payment) (e.g. `SUCCEEDED`, `DECLINED`, `PENDING`, `REJECTED`, `CANCELED`, `ERROR`). Use for UI updates or analytics. | +| `yunoError(message, data)` | function | No | Callback invoked when an error occurs during the flow. Receives an error message and optional data object for debugging. | +| `onLoading` | function | No | Callback invoked when loading state changes (e.g. SDK fetching config, processing payment). Use to show or hide your own loader. | + +### Card form options (`card`) + +| Parameter | Type | Required | Description | +| --------------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `card.type` | string | No | Layout type for the card form. Options: `'step'` or `'extends'`. Affects how the form is displayed in the checkout. | +| `card.styles` | string | No | Custom CSS string injected into the iframe to style the card form. Use to match your brand. | +| `card.cardSaveEnable` | boolean | No | When `true`, shows a checkbox to save or enroll the card for future use. Default `false`. Requires backend support for vaulting. | +| `card.texts` | object | No | Custom text for card form buttons and labels. Keys depend on SDK version (e.g. placeholders, button labels). | +| `card.onChange` | function | No | Callback when card form state changes (loading, completed, network selected, reset). Receives `{ error, data }`; `data` can include IIN/BIN and instalment options. Use BIN for real-time tax calculations. | +| `card.isCreditCardProcessingOnly` | boolean | No | When `true`, forces card transactions to process as credit only. Useful where the card can act as both credit and debit. | + +### Render mode + +| Parameter | Type | Required | Description | +| ---------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `renderMode` | object | No | Controls how payment forms are displayed. Omit to use defaults. | +| `renderMode.type` | string | No | `'modal'` (default) or `'element'`. Modal shows forms in an overlay; element embeds in the given DOM element. | +| `renderMode.elementSelector` | object | No* | Required if `type` is `'element'`. Provide `apmForm` (selector where APM UI is rendered) and `actionForm` (selector for button/area that opens provider-specific steps, e.g. PIX QR). | + + +### Custom texts + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `texts` | object | No | Custom text for payment form buttons and labels (e.g. `customerForm.submitButton`, `paymentOtp.sendOtpButton`). Use to match your application language or branding. | + +## Enrollment parameters (full reference) + +Parameters for `yuno.mountEnrollment`. All parameters used in [Enrollment flows (Web)](web-enrollment) are listed here with full detail. + +| Parameter | Type | Required | Description | +| ---------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `customerSession` | string | Yes | Customer session ID from your backend (Create customer session API). Required. Associates the enrolled payment method with a specific customer. | +| `countryCode` | string | Yes | ISO country code (e.g. `US`, `BR`). Determines available enrollment options. See [Country coverage](country-coverage). | +| `language` | string | No | Language code for the UI (e.g. `en`, `en-US`). Defaults to browser language when available. | +| `showLoading` | boolean | No | When `true`, shows the loading spinner during enrollment. Default `true`. | +| `onLoading` | function | No | Callback when loading state changes during enrollment. | +| `elementSelector` | string | No | CSS selector where the enrollment form mounts. Required when not using default modal behavior. | +| `card` | object | No | Card form options (same structure as payment flows: `type`, `styles`, `texts`, `onChange`, `isCreditCardProcessingOnly`, etc.). | +| `yunoEnrollmentStatus` | function | No | Callback when enrollment ends. Receives `vaultedToken` and `status`. Status values: `CREATED`, `EXPIRED`, `REJECTED`, `READY_TO_ENROLL`, `ENROLL_IN_PROCESS`, `UNENROLL_IN_PROCESS`, `ENROLLED`, `DECLINED`, `CANCELED`, `ERROR`, `UNENROLLED`. | +| `issuersFormEnable` | boolean | No | When `true`, shows the issuer (bank) list form. Optional. | +| `texts` | object | No | Custom text for enrollment form buttons and labels. | + +## Mount external buttons + +Use the `mountExternalButtons` method to render PayPal, Google Pay, and Apple Pay buttons in custom locations within your UI. This gives you control over where these buttons are displayed. + +```javascript +await yuno.mountExternalButtons([ + { + paymentMethodType: 'APPLE_PAY', + elementSelector: '#apple-pay', + }, + { + paymentMethodType: 'GOOGLE_PAY', + elementSelector: '#google-pay', + }, + { + paymentMethodType: 'PAYPAL', + elementSelector: '#paypal', + }, +]); +``` + +### Parameters + +| Parameter | Description | +| :------------------ | :------------------------------------------------------------------------------------------------------------- | +| `paymentMethodType` | The payment method type. Must be `'APPLE_PAY'`, `'GOOGLE_PAY'`, or `'PAYPAL'`. | +| `elementSelector` | The CSS selector for the HTML element where the button should be rendered (e.g., `'#apple-pay'`, `'.button'`). | + +### Unmounting buttons + +You can unmount a single external button by payment method type: + +```javascript +yuno.unmountExternalButton('APPLE_PAY'); +``` + +Or unmount all external buttons at once: + +```javascript +yuno.unmountAllExternalButtons(); +``` + +## Enrolling payment methods + +You can enroll payment methods (store cards for future use) directly during the payment flow by setting `payment_method.vault_on_success = true` in the [checkout session creation](https://docs.y.uno/reference/the-checkout-session-object). + +When `vault_on_success` is set to `true`: + +* The payment method will be automatically enrolled if the payment status is `SUCCEEDED` +* If the payment does not succeed, no vaulting will occur +* The payment response will include a `vaulted_token` that you can use for future transactions + +**Example**: + +```json +{ + "account_id": "...", + ... + "payment_method": { + "vault_on_success": true + } +} +``` + +To generate and receive a `vaulted_token` when `vault_on_success = true`, the payment must reference an existing Yuno customer through `customer_payer.id` in the checkout session. Creating or sending the customer data inline inside the payment request does not create the customer on our side, so no vaulting will occur. + +For enrollment flows, see [Enrollment flows (Web)](enrollment-flows-web). diff --git a/SDKs/Overview/Release Notes/_order.yaml b/SDKs/Overview/Release Notes/_order.yaml new file mode 100644 index 000000000..635ee9ce6 --- /dev/null +++ b/SDKs/Overview/Release Notes/_order.yaml @@ -0,0 +1,3 @@ +- web +- android +- ios diff --git a/docs/Yuno SDKs/android-sdks/release-notes-android.md b/SDKs/Overview/Release Notes/android.md similarity index 100% rename from docs/Yuno SDKs/android-sdks/release-notes-android.md rename to SDKs/Overview/Release Notes/android.md diff --git a/docs/Yuno SDKs/ios-sdks/release-notes-ios.md b/SDKs/Overview/Release Notes/ios.md similarity index 100% rename from docs/Yuno SDKs/ios-sdks/release-notes-ios.md rename to SDKs/Overview/Release Notes/ios.md diff --git a/docs/Yuno SDKs/web-sdks/release-notes-web.md b/SDKs/Overview/Release Notes/web.md similarity index 100% rename from docs/Yuno SDKs/web-sdks/release-notes-web.md rename to SDKs/Overview/Release Notes/web.md diff --git a/SDKs/Overview/_order.yaml b/SDKs/Overview/_order.yaml new file mode 100644 index 000000000..ff3661d5d --- /dev/null +++ b/SDKs/Overview/_order.yaml @@ -0,0 +1,7 @@ +- choose-integration +- quickstart +- understanding-flows +- country-coverage +- languages-supported +- References +- Release Notes diff --git a/SDKs/Overview/choose-integration.md b/SDKs/Overview/choose-integration.md new file mode 100644 index 000000000..8fd829c6b --- /dev/null +++ b/SDKs/Overview/choose-integration.md @@ -0,0 +1,45 @@ +--- +title: Choose the Right Integration for You +deprecated: false +hidden: false +metadata: + robots: index +--- +Within each platform's SDK, Yuno offers various **integration methods** allowing varying degrees of control over the UI and user experience. + +The integration method you select affects the level of maintenance effort required, the ease of managing payment methods (which may range from no-code configuration in the Yuno Dashboard to hands-on developer work), and your compliance obligations, since some integration types require certifications such as **PCI-DSS** or **ISO**. + +> πŸ‘ Recommended Integration +> +> We recommend using **Full Checkout** for the most straightforward solution with pre-built UI and automatic payment method display. It covers the most common scenarios with the least integration effort. + +## Integration Types + +Below, you can see the specifications for each integration type. + +| Feature | [Full Checkout](#full-checkout) | [Secure Fields](#secure-fields) | +| :--- | :---: | :---: | +| Add new payment methods without code | βœ… | ❌ | +| Handle hundreds of payment methods with a single API | βœ… | βœ… | +| Tokenize cards and payment methods without code | βœ… | βœ… | +| Use Yuno's PCI-DSS Certification | βœ… | βœ… | +| Use 3D Secure | βœ… | βœ… | +| Use an antifraud solution without code | βœ… | βœ… | +| Set checkout conditions using our dashboard | βœ… | ❌ | +| Customize the look and feel of your checkout using our dashboard | βœ… | ❌ | + +### Full Checkout + +Our most comprehensive integration solution. It streamlines implementation, reduces maintenance and operational overhead, and removes the need to handle compliance, all while offering maximum flexibility. + +* **User experience management**: Yuno manages the user experience while allowing you to customize the checkout to match your brand. +* **Payment method configuration**: Add and configure payment methods directly from the dashboard, with no extra coding. +* **Flexibility and simplicity**: Ideal for businesses that want full control over the experience without managing backend complexity. + +### Secure Fields + +A secure and seamless checkout solution using prebuilt UI components (Web Only): + +* **Secure data collection**: Simplifies the process of collecting and tokenizing payment card details. +* **PCI compliance**: Ensures a PCI-compliant experience while maintaining a customized UI. +* **Balanced solution**: Ideal for businesses looking for a balance between security and flexibility. diff --git a/docs/Yuno SDKs/country-coverage.md b/SDKs/Overview/country-coverage.md similarity index 100% rename from docs/Yuno SDKs/country-coverage.md rename to SDKs/Overview/country-coverage.md diff --git a/docs/Yuno SDKs/languages-supported.md b/SDKs/Overview/languages-supported.md similarity index 100% rename from docs/Yuno SDKs/languages-supported.md rename to SDKs/Overview/languages-supported.md diff --git a/SDKs/Overview/quickstart.md b/SDKs/Overview/quickstart.md new file mode 100644 index 000000000..a151bfe63 --- /dev/null +++ b/SDKs/Overview/quickstart.md @@ -0,0 +1,358 @@ +--- +title: Quickstart Guide +deprecated: false +hidden: false +metadata: + robots: index +--- + +Welcome to the Yuno SDKs quickstart guide. This guide shows you how to easily implement our full payment flow, Yuno's most straightforward solution with pre-built UI and automatic payment method display. + +Choose your platform and follow the steps to start process your first payments with Yuno. + +## Web SDK integration + +### 1. Install + +```bash +npm install @yuno-payments/sdk-web +``` + +Or include via CDN: + +```html + +``` + +### 2. Initialize and process payment + +```javascript +import { Yuno } from '@yuno-payments/sdk-web'; + +// Initialize SDK +const yuno = await Yuno.initialize('your-public-api-key'); + +// Create checkout session on your backend +// Your backend calls: POST https://api-sandbox.y.uno/v1/checkout/sessions +const session = await fetch('/api/create-session', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + customer_id: 'customer-123', + amount: { currency: 'USD', value: 1000 }, + country: 'US' + }) +}).then(r => r.json()); + +// Configure checkout +yuno.startCheckout({ + checkoutSession: session.checkout_session, + elementSelector: '#payment-form', + countryCode: 'US', + async yunoCreatePayment(oneTimeToken) { + // Your backend calls: POST https://api-sandbox.y.uno/v1/payments + // with { payment_method: { token: oneTimeToken }, checkout_session: ... } + const payment = await fetch('/api/process-payment', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + one_time_token: oneTimeToken, + checkout_session: session.checkout_session + }) + }).then(r => r.json()); + + // Required for async payment methods (3DS, PIX, etc.) + yuno.continuePayment(); + } +}); + +// Mount payment form +yuno.mountCheckout(); +``` + +### 3. Add HTML container and trigger payment + +```html +
+ + + +``` + +**Test with**: Card `4111 1111 1111 1111`, any future date, any CVV + +For a comprehensive overview of all Web SDK parameters, see [Web SDK Common Reference](web-sdk-common-reference). + +[Complete Web guide β†’](payment-flows-web) + +## iOS + +### 1. Install + +**CocoaPods**: +```ruby +pod 'YunoSDK', '~> 2.11.1' +``` + +**Swift Package Manager**: +```swift +dependencies: [ + .package(url: "https://github.com/yuno-payments/yuno-sdk-ios", from: "2.11.1") +] +``` + +### 2. Initialize and implement delegate + +```swift +import YunoSDK + +// Initialize in AppDelegate or App struct +Yuno.initialize( + apiKey: "your-public-api-key", + config: YunoConfig() +) + +// In your view controller - implement YunoPaymentDelegate +class PaymentViewController: UIViewController, YunoPaymentDelegate { + + // Required delegate properties + var checkoutSession: String { "session-from-backend" } + var countryCode: String { "US" } + var language: String? { "en" } + var viewController: UIViewController? { self } + + override func viewDidLoad() { + super.viewDidLoad() + displayPaymentMethods() + } + + func displayPaymentMethods() async { + // Get payment methods view + let paymentView = await Yuno.getPaymentMethodViewAsync(delegate: self) + view.addSubview(paymentView) + // Add constraints... + } + + // Required: Create payment with one-time token + func yunoCreatePayment(with token: String) { + // Call your backend: POST /v1/payments + createPaymentOnBackend(token: token) { result in + // After payment creation, continue for async methods + Yuno.continuePayment() + } + } + + // Required: Handle payment result + func yunoPaymentResult(_ result: Yuno.Result) { + switch result { + case .succeeded: + print("Payment succeeded!") + case .fail: + print("Payment failed") + case .processing: + print("Payment processing") + default: + break + } + } +} + +// Start payment when user taps pay button +@IBAction func payButtonTapped(_ sender: UIButton) { + Yuno.startPayment(showPaymentStatus: true) +} +``` + +**Test with**: Card `4111 1111 1111 1111`, any future date, any CVV + +For a comprehensive overview of all iOS SDK parameters, see [iOS SDK Common Reference](ios-sdk-common-reference). + +[Complete iOS guide β†’](payment-flows-ios) + +## Android + +### 1. Install + +**build.gradle**: +```kotlin +repositories { + maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" } +} + +dependencies { + implementation 'com.yuno.payments:android-sdk:2.9.0' +} +``` + +### 2. Initialize and process payment + +**Initialize in Application**: +```kotlin +class MyApplication : Application() { + override fun onCreate() { + super.onCreate() + Yuno.initialize( + this, + publicApiKey = "your-public-api-key", + config = YunoConfig() + ) + } +} +``` + +**In Activity/Fragment**: +```kotlin +import com.yuno.payments.Yuno + +class PaymentActivity : ComponentActivity() { + private var checkoutSession: String? = null + + override fun onCreate(savedInstanceState: Bundle?) { + super.onCreate(savedInstanceState) + + // Create checkout session on your backend first + // Your backend calls: POST https://api-sandbox.y.uno/v1/checkout/sessions + lifecycleScope.launch { + val session = createCheckoutSession() // Your backend call + checkoutSession = session.id + + // Start checkout with session + startCheckout( + checkoutSession = session.id, + countryCode = "US", + callbackPaymentState = { state, subState -> + when (state) { + "SUCCEEDED" -> println("Payment succeeded!") + "FAILED" -> println("Payment failed") + "PROCESSING" -> println("Payment processing") + "REJECT" -> println("Payment rejected") + else -> println("Payment state: $state") + } + } + ) + } + + setContent { + var paymentMethodSelected by remember { mutableStateOf(false) } + + Column( + modifier = Modifier + .fillMaxSize() + .verticalScroll(rememberScrollState()) + ) { + // Display payment methods + PaymentMethodListViewComponent( + activity = this@PaymentActivity, + onPaymentSelected = { isSelected -> + paymentMethodSelected = isSelected + } + ) + + // Pay button + Button( + onClick = { + startPayment( + showStatusYuno = true, + callbackOTT = { token -> + token?.let { ott -> + // Call your backend: POST /v1/payments + // with { payment_method: { token: ott }, checkout_session: ... } + createPayment(ott, checkoutSession!!) + + // Required for async payment methods + continuePayment() + } + } + ) + }, + enabled = paymentMethodSelected + ) { + Text("Pay Now") + } + } + } + } +} +``` + +**Test with**: Card `4111 1111 1111 1111`, any future date, any CVV + +For a comprehensive overview of all Android SDK parameters, see [Android SDK Common Reference](android-sdk-common-reference). + +[Complete Android guide β†’](payment-flows-android) + + +## Backend integration + +Your backend must implement two API endpoints to work with Yuno: + +### 1. Create checkout session + +Before displaying the payment UI, your backend creates a checkout session: + +- **Endpoint**: `POST https://api-sandbox.y.uno/v1/checkout/sessions` +- **Required**: Customer ID, amount, country +- **Returns**: `checkout_session` ID (used in SDK) +- **Reference**: [Create checkout session API](https://docs.y.uno/reference/create-checkout-session) + +**Example request**: +```json +{ + "country": "US", + "customer_payer": { + "id": "customer-123" + }, + "amount": { + "currency": "USD", + "value": "2500" + } +} +``` + +### 2. Create payment + +In the One-Time Token (OTT) callback, your backend creates the payment: + +- **Endpoint**: `POST https://api-sandbox.y.uno/v1/payments` +- **Required**: One-time token (from SDK callback), checkout session +- **Returns**: Payment status and `sdk_action_required` field +- **Reference**: [Create payment API](https://docs.y.uno/reference/create-payment) + +**Example request**: +```json +{ + "payment_method": { + "token": "one-time-token-from-sdk" + }, + "checkout": { + "session": "checkout-session-id" + } +} +``` + +**Important**: If the API response has `sdk_action_required: true`, you must call the SDK's `continuePayment()` method to complete async payment methods (3DS authentication, PIX, bank redirects, etc.). + +## Parameters + +Primary parameters used in this quickstart: + +| Parameter | Description | +| --------- | ----------- | +| `publicKey` / `apiKey` | Your Yuno public API key (frontend). From [Yuno Dashboard](https://dashboard.y.uno/) β†’ **Developers** > **Credentials**. | +| `checkoutSession` | Checkout session ID returned by your backend (create session endpoint). Required to start payment. | +| `countryCode` | ISO country code for the payment (e.g. `US`, `CO`). See [Country coverage](country-coverage). | +| `elementSelector` (Web) | CSS selector for the element where the payment form is mounted (e.g. `#payment-form`). | + +Full parameter reference: [Payment flows (Web)](payment-flows-web), [Payment flows (iOS)](payment-flows-ios), [Payment flows (Android)](payment-flows-android). + +## Test cards + +| Card Number | Scenario | +| ------------------- | -------------- | +| 4111 1111 1111 1111 | Success | +| 4000 0000 0000 0002 | Declined | +| 4000 0000 0000 3220 | 3DS Challenge | \ No newline at end of file diff --git a/SDKs/Overview/understanding-flows.md b/SDKs/Overview/understanding-flows.md new file mode 100644 index 000000000..5f0ddc8ab --- /dev/null +++ b/SDKs/Overview/understanding-flows.md @@ -0,0 +1,75 @@ +--- +title: Understanding Payment and Enrollment Flows +deprecated: false +hidden: false +metadata: + robots: index +--- + +In Yuno SDKs, **payment flows** and **enrollment flows** are separate. Payment is the process of completing a transaction; enrollment is the process of saving a payment method (e.g. a card) to a customer account for future use. This page explains both flows at a high level with diagrams and step sequences. Use the Quickstart guide and platform flow pages for implementation details. + +## Payment flow + +The SDK provides a unified payment experience: customers complete transactions using multiple payment methods within a single integration. The diagram below illustrates the main payment workflow. + +![Full (Web) payment flow](https://files.readme.io/0b97d1a-Diagrama_-_Full_SDK.png) + +### Payment flow steps + +1. Merchant Server: Create Customer β†’ Yuno Server: Creates Customer +2. Merchant Client: Initiate Checkout β†’ Merchant Server: Create Checkout session +3. Merchant Server: Create Checkout session β†’ Yuno Server: Creates Checkout session +4. Merchant Client: Initiate Checkout β†’ Initiate SDK to continue payment flow +5. Merchant Client: Initiate SDK to continue payment flow β†’ Yuno SDK: Receive checkout session +6. Yuno SDK: Receive checkout session β†’ List payment methods +7. Yuno SDK: List payment methods β†’ User selects payment methods +8. Yuno SDK: User selects payment methods β†’ Callback with the one-time token +9. Yuno SDK: Callback with the one-time token β†’ Merchant Client: Receive one-time token (single use) +10. Merchant Client: Receive one-time token (single use) β†’ Initiate payment +11. Merchant Client: Initiate payment β†’ Initiate SDK to continue payment flow +12. Merchant Client: Initiate SDK to continue payment flow β†’ Yuno SDK: Continue with the payment flow +13. Yuno SDK: Continue with the payment flow β†’ Show screen for the user to complete payment +14. Yuno SDK: Show screen for the user to complete payment β†’ Display payment result (optional) +15. Merchant Client: Initiate payment β†’ Merchant Server: Create payment +16. Merchant Server: Create payment β†’ Yuno Server: Creates payment in the payment provider + +### Payment flow using a vaulted token + +If a customer has an enrolled payment method, they can use a **vaulted token** to pay without entering payment details again. + +![Vaulted token payment flow](https://files.readme.io/e257d04-Diagrama_-_Vaulted_token_Full.png) + +#### Vaulted token flow steps + +1. Merchant Client: Initiate checkout β†’ Merchant Server: Create Customer +2. Merchant Server: Create Customer β†’ Yuno Server: Create Customer +3. Merchant Client: Initiate SDK with the checkout session β†’ Yuno SDK: Receive checkout session +4. Yuno SDK: Receive checkout session β†’ List payment methods +5. Yuno SDK: List payment methods β†’ User selects payment methods +6. Yuno SDK: User selects payment method β†’ Callback with the one-time token +7. Yuno SDK: Callback with the one-time token β†’ Merchant Client: Initiate payment +8. Merchant Client: Initiate payment β†’ Merchant Server: Create payment +9. Merchant Server: Create payment β†’ Yuno Server: Creates payment in the payment provider +10. Merchant Client: Show payment result β†’ Merchant Server: Receive payment result +11. Merchant Server: Receive payment result β†’ Yuno Server: Provides payment result + +## Enrollment flow + +**Enrollment** is the process of saving a payment method (e.g. a card) to a customer’s account so it can be used later (e.g. with a vaulted token). Full Checkout supports enrollment; the diagram below describes the enrollment workflow. + +![Enrollment flow](https://files.readme.io/deacb45-Diagrama_-_SDK_Lite_enrollment.png) + +### Enrollment flow steps + +1. Merchant Server: Create Customer β†’ Yuno Server: Creates Customer +2. Merchant Client: Add payment method β†’ Merchant Server: Create customer session +3. Merchant Server: Create customer session β†’ Yuno Server: Creates customer session +4. Merchant Client: Display payment methods to enroll β†’ Merchant Server: Request available payment methods to enroll +5. Merchant Server: Request available payment methods to enroll β†’ Yuno Server: Returns available payment method +6. Merchant Client: Display payment methods to enroll β†’ Merchant Client: User selects payment method to enroll +7. Merchant Client: User selects payment method to enroll β†’ Merchant Client: Initiate enrollment +8. Merchant Client: Initiate enrollment β†’ Merchant Client: Initiate SDK to continue enrollment +9. Merchant Client: Initiate SDK to continue enrollment β†’ Yuno SDK: Continue enrollment flow +10. Yuno SDK: Continue enrollment flow β†’ Yuno SDK: Shows screens for the user to complete enrollment +11. Merchant Server: Receive enrollment result via webhook β†’ Yuno Server: Receive enrollment results from payment provider +12. Yuno Server: Receive enrollment results from payment provider β†’ Yuno SDK: Display enrollment result (optional) \ No newline at end of file diff --git a/SDKs/_order.yaml b/SDKs/_order.yaml new file mode 100644 index 000000000..3bc21095d --- /dev/null +++ b/SDKs/_order.yaml @@ -0,0 +1,4 @@ +- Overview +- Full Checkout +- Customization +- Card Enrollment diff --git a/docs/Yuno SDKs/_order.yaml b/Yuno SDKs/_order.yaml similarity index 100% rename from docs/Yuno SDKs/_order.yaml rename to Yuno SDKs/_order.yaml diff --git a/docs/Yuno SDKs/android-sdks/_order.yaml b/Yuno SDKs/android-sdks/_order.yaml similarity index 84% rename from docs/Yuno SDKs/android-sdks/_order.yaml rename to Yuno SDKs/android-sdks/_order.yaml index 0348ed11f..63c0aaaa4 100644 --- a/docs/Yuno SDKs/android-sdks/_order.yaml +++ b/Yuno SDKs/android-sdks/_order.yaml @@ -1,5 +1,4 @@ - payment-flows-android -- copy-of-payment-flows - enrollment-flows-android - android-sdk-common-reference - release-notes-android diff --git a/Yuno SDKs/android-sdks/android-customizations.md b/Yuno SDKs/android-sdks/android-customizations.md new file mode 100644 index 000000000..cc3bf49a2 --- /dev/null +++ b/Yuno SDKs/android-sdks/android-customizations.md @@ -0,0 +1,571 @@ +--- +title: SDK Customizations +deprecated: false +hidden: false +metadata: + robots: index +--- + +Modify Yuno Android SDK styles (colors, text, buttons) to align payment forms and checkout with your brand. Element structure stays uniform. For all Android SDK parameters and config options, see [Android SDK Common Reference](android-sdk-common-reference). + +## General guidelines + +Yuno Android SDK supports XML themes and styles, which should be defined within your application's styles. Android customizations are a work in progress and are continuously updated. + +## Customizable elements + +Elements you can modify for a personalized style. Some customizations require version 1.13.0 or higher. + +- [Font styles](#font-styles) +- [Button styles](#button-styles) +- [Color styles](#color-styles) +- [Text styles](#text-styles) + +### Font styles + +You can override Yuno Android SDK fonts if you want to use your font family. You can override the following font styles: + +- `YunoRegularFont` +- `YunoMediumFont` +- `YunoBoldFont` + +Example (font style): + +```xml + + + + + +``` + +### Button styles + +Override button styles; available options depend on SDK version. Buttons you can customize: + +| Versions before v1.10.0 | Version v1.10.0 and higher | Version v1.13.0 and higher | +| --------------------------- | ----------------------------------- | ----------------------------------- | +| `Button.Normal.White` | `Button.Small.NeutralB` | `Button.Normal` | +| `Button.Normal.Green` | `Button.Normal.NeutralB` | `Button.Small` | +| `Button.Normal.Purple` | `Button.Normal.Green` | `Button.Normal.NeutralW` | +| `Button.Normal.Purple.Big` | `Button.Normal.NeutralW.TextGrey4` | `Button.Normal.NeutralW.TextGrey4` | +| | `Button.Normal.NeutralW` | `Button.Normal.Green` | +| | `Button.Small` | `Button.Normal.NeutralB` | +| | `Button.Normal` | `Button.Small.NeutralB` | + +For each style, you can set the following attributes: + +```kotlin + + + + + + + + + + + + + + + +``` + +Example (`Button.Normal.NeutralB` and button font): + +```kotlin + +``` + +### Color styles + +Override color styles to personalize the SDK; options depend on SDK version. Color styles by version: + +| Versions before v1.10.0 | Version v1.10.0 and higher | Version v1.13.0 and higher | +| ------------------------- | --------------------------- | ------------------------------ | +| `yuno_purple_light` | `neutral_b` | `on_focus_outlined_text_view` | +| | `neutral_b_60_alpha` | `primary_4` | +| | `neutral_w` | `primary_5` | +| | `neutral_w_30_alpha` | `secondary_1` | +| | `grey_0` | `secondary_2` | +| | `grey_1` | `secondary_3` | +| | `grey_2` | `secondary_4` | +| | `grey_3` | `secondary_5` | +| | `grey_4` | `secondary_6` | +| | `grey_5` | `tertiary_1` | +| | `primary_1` | `tertiary_2` | +| | `primary_2` | `tertiary_3` | +| | `primary_3` | `tertiary_4` | + +Example (colors, SDK v1.13.0+): + +```xml +#fff000 +#282A30 +``` + +### Text styles + +You can override Yuno Android SDK text styles to personalize the SDK's appearance. + +> This feature is only available for SDK version 1.13.0 or higher. + +Customization attributes per text style: + +| Text Style | Parent Style | Customizable Attributes | +| --------------------- | ------------------ | ------------------------ | +| `YunoRegularFont` | | `android:fontFamily` | +| `TextMicro` | `YunoRegularFont` | `android:textSize` | +| `TextSmall` | `YunoRegularFont` | `android:textSize` | +| `TextBody` | `YunoRegularFont` | `android:textSize` | +| `TextSubTitle` | `YunoRegularFont` | `android:textSize` | +| `TextH4` | `YunoRegularFont` | `android:textSize` | +| `TextH3` | `YunoRegularFont` | `android:textSize` | +| `TextH2` | `YunoRegularFont` | `android:textSize` | +| `TextH1` | `YunoRegularFont` | `android:textSize` | +| `TextH1Super` | `YunoRegularFont` | `android:textSize` | +| `TextMicro.NeutralB` | `TextMicro` | `android:textColor` | +| `TextMicro.NeutralB` | `TextMicro` | `android:textColorHint` | +| `TextSmall.NeutralB` | `TextSmall` | `android:textColor` | +| `TextSmall.NeutralB` | `TextSmall` | `android:textColorHint` | + +Example (text customizations): + +```kotlin + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +## Create your own card form flow + +The first step to creating your card form flow is to create a new layout resource file called `screen_payment_card_form.xml` to override the current XML and implement your design. + +After creating the `screen_payment_card_form.xml` file, you can define your own design. You need to use the Yuno Secure Fields components, which ensures that the Yuno SDK can retrieve credit card information during the checkout. Below, you will find a list of all the components you can use to change the design: + +> 🚧 Changing Components +> +> When changing the Yuno Android SDK components, you must use them with their defined Android `id`. + +### v1.10.0 or higher + +Additional components are available for the Yuno SDK version v1.10.0 or higher. These components are listed in the [subsection below](#components-available-for-v1100-and-higher). + +- `CloseButton`: Button to close the form. + +```xml + +``` + +- `CardNumberEditText`: Field where the user can enter the credit card number. + +```xml + +``` + +- `CardDataStackView`: Field where the user can enter the credit card's expiration date and verification code (CVV/CVC). + +```xml + +``` + +- `TextView` for Voucher card type: This is a copy Yuno SDK shows when the card is `VOUCHER `type, you must set it below the CVV field. + +```xml + +``` + +- `TextFieldItemView `for card holder's name: Field where the user can enter the credit card holder's name. + +```xml + +``` + +- `SpinnerFieldItemView` for identification document type: A selector where the credit card holder can choose their identification document type. + +```xml + +``` + +- `TextFieldItemView` for identification document number: Field where the user can enter the credit card holder's identification document number. + +```xml + +``` + +- `PhoneInformationView `for customer's phone number: Field where the user can enter his phone number if required. In addition to providing the Android `id`, it's required to have `gone` visibility. + +```xml + +``` + +- `Installments`: Component that shows the spinner of card installments. In addition to providing the Android `id`, it's required to have `gone` visibility, and you need to add the `ShimmerFrameLayout` dependency: `implementation 'com.facebook.shimmer:shimmer:0.5.0'`. + +```xml + + + + + + + + + + +``` + +- Yuno's `TextView`: A text to show that Yuno verified the form. + +```xml + +``` + +- `CustomYunoSwitch`: It's a switch component that lets the user choose if the card will be used as credit or debit. In addition to providing the Android `id`, it's required to have `gone` visibility. + +```xml + +``` + +- `CustomYunoSwitch`: A tooltip to show how the switch works. In addition to providing the Android `id`, it's required to have `gone` visibility. Yuno recommends positioning this component next to the switch. + +```xml + +``` + +- `AppCompatCheckBox`: A check box users can use to choose whether to save the credit card for future purchases. + +```xml + +``` + +- `Button`: It validates the card form and continues the payment process. When the user clicks this button, the SDK submits the form and sends the credit card information to Yuno. + +```xml +