Wallets

This section describes all the necessary steps for integrating the payment flow with Apple Pay and Google Pay wallets.

Marlim's partner for SDK integration with Android devices (Google Pay) and iOS devices (Apple Pay) is Yuno and will be the library responsible for orchestrating the entire payment process. We will discuss more about installing this package in your application for each platform in the following sections.

One of the significant changes between wallet payments and traditional transactions is in the response format, which can be both synchronous and asynchronous. In the case of wallets, transactions introduce a new synchronous status SENT, while the final transaction status update occurs asynchronously via webhook, indicating whether the payment was completed successfully or not.

1. Generating a session

To create a transaction with a Wallet, you will first need to create a Session.

Request Body Params

Property	Meaning
amount	Final amount to be charged with fees. Must be passed in cents.
item_id	Transaction ID in your platform. This ID is important as it will be used both in session creation and in the transaction creation stage.
customer[name]	Customer's full name.
customer[email]	Customer's email.
customer[phone_number]	Customer's phone number. Must be passed complete: Country Code (country code), Area Code (city code) and the NUMBER.
customer[document_number]	Customer's document number.
customer[address][zipcode]	ZIP Code (domestic customers) or ZIP (foreign customers) of the customer.
customer[address][country]	Customer's nationality in country code format. Only ISO 3166-1 alpha-2 (two-letter) format will be accepted. Ex: BR, US, UY...
customer[address][state]	State of customer's current address in State Code format. Ex: SP, RJ, MG...
customer[address][city]	City of customer's address.
customer[address][neighborhood]	Neighborhood of customer's address.
customer[address][street]	Street of customer's address.
customer[address][number]	Number of customer's address.

Response Object

Property	Meaning
`session_id`	Session ID that will be used in the checkout stage in the SDK application, so it's important that you reserve it.

Request

curl -X POST "https://api.marlim.co/v3/v2/wallets/session" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 100000,
  "item_id": "a4fe84db-bfaf-4fc0-a345-c6bc53cb5d4a",
  "customer[name]": "John Silva",
  "customer[email]": "john@silva.com.br",
  "customer[phone_number]": "+55119987654321",
  "customer[document_number]": "11122233344",
  "customer[address][zipcode]": "01122033",
  "customer[address][country]": "BR",
  "customer[address][state]": "SP",
  "customer[address][city]": "São Paulo",
  "customer[address][neighborhood]": "Downtown",
  "customer[address][street]": "Main Street",
  "customer[address][number]": "123"
}'

Response200

{
  "session_id": "886eb109-4149-41c3-8f2f-6c85545bda21"
}

Payment Methods

In the next device integration sections, you will need to add the payment_type chosen by the user. The available payment types are: GOOGLE_PAY or APPLE_PAY and must be filled exactly as described.

2. Device Integration

2.1 Android (Google Pay)

Prerequisites

To use the Yuno Android SDK, you need to meet the following system requirements:

The Yuno Android SDK requires your minSdkVersion to be 21 or higher
Your project must have Java 8 enabled and use AndroidX instead of older support libraries
The android-gradle-plugin version must be 4.0.0 or higher
The Proguard version must be 6.2.2 or higher
The kotlin-gradle-plugin version must be 1.4.0 or higher

SDK Installation

Step 1: Include the library in your project

Make sure the Yuno SDK file is included in your project through Gradle. Then, add the repository source using the following line of code:

maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }

After that, include the code below in the build.gradle file to add the Yuno SDK dependency to the application.

dependencies {
    implementation 'com.yuno.payments:android-sdk:{last_version}'
}

Permissions

Yuno SDK includes, by default, the INTERNET permission, which is necessary to make network requests.

<uses-permission android:name="android.permission.INTERNET" />

Required Imports

import com.yuno.payments.features.payment.startCheckout;
import com.yuno.payments.features.payment.startPaymentLite;
import com.yuno.payments.features.payment.ui.views.PaymentSelected;
import com.yuno.payments.features.payment.continuePayment;

Step 2: Initialize the SDK with the public key

If you haven't implemented a custom application, create one. In the onCreate() of your application class, call the initialization function (Yuno.initialize) as shown in the example below:

class CustomApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    Yuno.initialize(
      this,
      "public_key",
      config: YunoConfig,
    )
  }
}

Note

Marlim's Development or Support team will provide 2 keys (public_key), one for production environment and another for staging environment.

Use the YunoConfig data class to customize the SDK behavior. Include this configuration in Yuno.initialize:

data class YunoConfig(
    val language: YunoLanguage? = null,
    val isDynamicViewEnabled: Boolean = false,
)

In the table below you will find the descriptions of each available customization option.

Customization Option	Description
language	Set the language used to present the SDK. If you don't send or provide a null value, the Yuno SDK will use the device language. Available options are:`ENGLISH`, `SPANISH`, `PORTUGUESE`, `INDONESIAN` and `MALAY`.
isDynamicViewEnabled	Defines whether you want to use dynamic view. If you don't provide a value, the Yuno SDK will use `FALSE` as the option.

Step 3: Start the checkout process

To start a new payment process with the SDK, you need to call the startCheckout method in the onCreate of the activity that calls the SDK, this is where you will use the session_id generated in the previous step.

startCheckout(
  checkoutSession: "session_id",
  countryCode: "BR",
  callbackPaymentState: ((String?) -> Unit)?
)

Property	Meaning
callbackPaymentState	It's a function that returns the current payment process. Possible values: `SUCCEEDED`, `FAIL`, `PROCESSING`, `REJECT`, `INTERNAL_ERROR` and `CANCELED`

Step 4: Start the payment process

To start a payment process, you must call the startPaymentLite method

startPaymentLite(
    paymentSelected: PaymentSelected,
    callbackOTT:(String?) -> Unit,
    showPaymentStatus: Boolean,
)

PaymentSelected(
    type : String "payment_type",
)

Below is the description of the parameters needed to start the payment.

Property	Meaning
paymentSelected	Payment type selected by the user. Possible values `GOOGLE_PAY` or `APPLE_PAY`.
callbackOTT	A required function that returns the updated One Time Token (OTT), necessary to complete the payment process, which will be used to be sent to the Transactions endpoint.
showPaymentStatus	A boolean that specifies whether the payment status should be displayed in the interface.

2.2 iOS (Apple Pay)

Prerequisites

To use the Yuno iOS SDK, you need to meet the following system requirements:

Add CocoaPods or Swift Package Manager to your project
Use iOS version 14.0 or higher

Important

A few more steps are required that must be completed in the Apple Developer Panel in your account, described below.

Step 1: Create a merchant identifier

In the Apple Developer panel, register a merchant identifier following the steps:

Log in to the Apple Developer
In Certificates, Identifiers and Profiles, select Register a new identifier
Select Merchant IDs and click Continue

Add a Description to describe the merchant you are registering, such as Apple Pay Integration. For the Identifier, type the prefix merchant.com.y.uno.yourapp

Click Continue

Step 2: Create a payment processing certificate

To start, create a new directory (for example, Downloads/ApplePayFiles) to store the files needed to generate certificates. You should save certificates and other Apple Pay files during the process.

To create a PaymentProcessingCertificate on your MacOS, follow the steps presented below:

Open Keychain Access on your MacOS
In the Keychain Access application, Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority

Fill in the certificate information according to the following instructions:

Email Address: Enter your email address
Name: Enter a name for the private key (for example, ProcessingCertificate)
CA Email Address: Leave this field blank
Select Saved to disk
Select Let me specify key pair information

Click Continue
For the key pair, use the following settings:

Key Size: 256 bits
Algorithm: ECC

Save the CSR with the name CertificateSigningRequestPaymentProcessingCertificate.certSigningRequest in the previously created directory
Click Continue to finish creating the CSR

Step 3: Get the payment processing certificate

After creating the CSR, you need to obtain and convert the certificate. Follow the steps:

Access the Apple Developer portal
Select your merchant ID and click Create Certificate in Apple Pay Payment Processing Certificate

For Will payments associated with this Merchant ID be processed exclusively in China mainland?, select No
Click Upload a Certificate Signing Request, and select the previously created CSR named CertificateSigningRequestPaymentProcessingCertificate.certSigningRequest, and click Continue
Download the signed certificate (apple_pay.cer) from Apple and save it in the previously created directory (Downloads/ApplePayFiles)

Convert the certificate using the following command:

openssl x509 -inform DER -in apple_pay.cer -out apple_pay.pem

Step 4: Export private key information

Access Keychain Access on your computer
Locate the entry created earlier in Step 2 (for example, ProcessingCertificate)

Right-click and export the private key in .p12 format (example, ProcessingCertificate.p12)
Set a password (for example, ApplePayWallet) and save it in the previously created directory. You will need to provide your computer password to export the .p12
After exporting, we need to convert the private key. Access the directory where you saved the private key, open the terminal and run the following command:

openssl pkcs12 -in ProcessingCertificate.p12 -nocerts -nodes | sed -ne '/-BEGIN PRIVATE KEY-/,/-END PRIVATE KEY-/p' > ProcessingCertificatePrivateKey.pem

The private key content will be available in the ProcessingCertificatePrivateKey.pem file.

Step 5: Create a merchant identity certificate

To create a MerchantIdentityCertificate on your MacOS, follow the steps presented below:

Open Keychain Access on your MacOS
In the Keychain Access application, Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority
Fill in the certificate information according to the following instructions:

Email Address: Enter your email address
Name: Enter a name for the private key (for example, MerchantIdentityCertificate)
CA Email Address: Leave this field blank
Select Saved to disk
Select Let me specify key pair information

Click Continue
For the key pair, use the following settings:

Key Size: 2048 bits
Algorithm: RSA

Save the CSR with the name CertificateSigningRequestMerchantIdentityCertificate.certSigningRequest in the previously created directory (Downloads/ApplePayFiles)
Click Continue to finish creating the CSR

Step 6: Get the merchant identity certificate

After creating the CSR, you need to obtain and convert the certificate. Follow the steps:

Access the Apple Developer portal in Identifiers
Select your merchant ID
In Apple Pay Merchant Identity Certificate click Create Certificate

Click Upload a Certificate Signing Request and select the certificate created in Step 5 (CertificateSigningRequestMerchantIdentityCertificate.certSigningRequest)

Click Continue
Download the signed certificate (merchant_id.cer) from Apple and save it in the created directory (Downloads/ApplePayFiles)
Access the directory where you saved the certificate, open the terminal and run the following command to convert it to the required format:

openssl x509 -inform DER -in merchant_id.cer -out merchant_id.pem

Step 7: Export merchant private key

Access Keychain Access on your computer
Locate the entry created earlier in Step 5 (for example, MerchantIdentityCertificate)
Right-click and export the private key in .p12 format (example, MerchantIdentityCertificate.p12)
Set a password (for example, ApplePayWallet) and save it in the previously created directory (Downloads/ApplePayFiles). You will need to provide your computer password to export the .p12
After exporting, we need to convert the private key. Access the directory where you saved the private key, open the terminal and run the following command:

openssl pkcs12 -in MerchantIdentityCertificate.p12 -nocerts -nodes | sed -ne '/-BEGIN PRIVATE KEY-/,/-END PRIVATE KEY-/p' > MerchantIdentityCertificatePrivateKey.pem

The private key content will be available in the MerchantIdentityCertificatePrivateKey.pem file.

Step 8: Register merchant domains

As a final step, you need to register the merchant domains in the Apple Dashboard. Follow the steps below to complete the process:

Access the Apple Developer portal in Identifiers
Select your Merchant ID and click Add Domain in Merchant Domains
Enter the domain (for example, yourapp.com) and click Save

Important

After completing all the steps described above, you should send to Marlim the ApplePayFiles.zip folder with all the files generated in the previous steps.

Marlim will configure the necessary access with the Acquirer/Apple and release the iOS SDK integration for your team.

SDK Installation

Step 1: Include the library in your project

You can add the library using CocoaPods or Swift Package Manager.

CocoaPods

To add the Yuno SDK to your iOS project, you need to install the Yuno SDK. If you don't have a Podfile, follow the CocoaPods guide to create one. After creating the Podfile, you will integrate the Yuno SDK to Cocoapods by adding the line below to your Podfile.

pod 'YunoSDK', '~> 1.1.22'

Then, you need to run the installation:

pod install

Swift Package Manager

To add the Yuno SDK to your iOS project, you need to install the Swift Package Manager. With the Swift package configured, add Yuno SDK as a dependency, as presented in the following code block:

dependencies: [
    .package(url: "https://github.com/yuno-payments/yuno-sdk-ios.git", .upToNextMajor(from: "1.1.17"))
]

3. Start a Transaction

After completing the previously described steps, you will have 3 new fields that must be sent to a new endpoint dedicated to wallet-type transactions: transactions/wallets

Property	Meaning
wallet[payment_type]	Payment type selected by the user. Possible values `GOOGLE_PAY` or `APPLE_PAY`.
wallet[ott]	One Time Token (OTT) generated by the Yuno SDK and received in the callbackOTT.
wallet[session_id]	Session ID generated at the beginning of the payment process.

Request

curl -X POST "https://api.marlim.co/v3/transactions/wallets" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 1000000,
  "amount": 1039501,
  "installments": "1",
  "type": "remittance",
  "currency_amount": 150000,
  "currency_abbreviation": "EUR",
  "item_id": "a4fe84db-bfaf-4fc0-a345-c6bc53cb5d4a",
  "item_url": "123456789",
  "customer[external_id]": "11122233344",
  "customer[name]": "John Silva",
  "customer[email]": "john@silva.com.br",
  "customer[phone_number]": "+55119987654321",
  "customer[document_number]": "11122233344",
  "customer[address][zipcode]": "01122033",
  "customer[address][country]": "BR",
  "customer[address][state]": "SP",
  "customer[address][city]": "São Paulo",
  "customer[address][neighborhood]": "Downtown",
  "customer[address][street]": "Main Street",
  "customer[address][number]": "123",
  "soft_descriptor": "Your Company",
  "wallet": {
    "payment_type": "GOOGLE_PAY",
    "ott": "81817dc7-1061-4282-8743-b239c8c5a93e",
    "session_id": "886eb109-4149-41c3-8f2f-6c85545bda21"
  }
}'

Response200

{
  "status": "sent",
  "transaction_id": "008ktCGUnBauanAt7sW",
  "date_created": "2025-07-29T11:38:57.908Z",
  "date_updated": "2025-07-29T11:38:57.908Z",
  "net_value": 1000000,
  "amount": 1039501,
  "paid_amount": 0,
  "installments": "1"
}

Payment confirmation will be made via webhook, after the user completes the payment process on the device with the selected wallet.

4. ContinuePayment

After sending to start a transaction, in your request callback, the continuePayment() method from the Yuno SDK should be called. This method will require some action, opening the native wallet modals for the user to complete the payment - add card data or select a previously registered card.

Android

continuePayment(
    showPaymentStatus: Boolean, // Optional - Default true
    callbackPaymentState: ((String?) -> Unit)?, // Optional - Default null
)

Important

For the user to completely complete the payment process in SANDBOX, it is necessary that they have a credit card previously registered in their Google account (Google Pay wallet) and that it be a valid card issued by an Issuing Bank, test cards should not be used.

If the user doesn't have a registered card, they will be instructed to add one before continuing with the transaction, but the SDK may return an error due to Google Pay validation. In Marlim tests this flow failed in the sandbox environment.

This process does not occur in PRODUCTION, as Google Pay can validate a card added at the time of purchase.

iOS

Yuno.continuePayment(showPaymentStatus: Bool)

To show your payment status screens, you should send FALSE in showPaymentStatus. Then, get the payment status by callback call.

5. Webhooks

After the user completes the payment on the device, the Wallet sends an update to our Acquirer, informing whether the transaction was successful or not. Marlim, in turn, sends the Webhook with transaction data to your servers.

Request

curl -X POST "https://yourapp.com/order/7ea1a5d4-fd74-41ae-b150-07fa36c260fa/callback" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-d '{
  "event": "transaction_status_changed",
  "transaction_id": "r9U3U1T0ZtBp3EceRfup",
  "item_id": "7ea1a5d4-fd74-41ae-b150-07fa36c260fa",
  "old_status": "processing",
  "desired_status": "paid",
  "current_status": "paid",
  "nsu": "587386",
  "authorization_code": "891482",
  "acquirer_status_code": "0000",
  "date_created": "2025-07-29T11:38:57.908Z",
  "date_updated": "2025-07-29T11:38:57.908Z",
  "net_value": 1000,
  "amount": 1094,
  "paid_amount": 1094,
  "refunded_amount": 0,
  "installments": "4",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "444455",
  "card_last_digits": "2222"
}'

1. Generating a session​

Request Body Params​

Response Object​

Payment Methods​

2. Device Integration​

2.1 Android (Google Pay)​

Prerequisites​

SDK Installation​

Step 1: Include the library in your project​

Step 2: Initialize the SDK with the public key​

Step 3: Start the checkout process​

Step 4: Start the payment process​

2.2 iOS (Apple Pay)​

Prerequisites​

Step 1: Create a merchant identifier

Step 2: Create a payment processing certificate

Step 3: Get the payment processing certificate

Step 4: Export private key information

Step 5: Create a merchant identity certificate

Step 6: Get the merchant identity certificate

Step 7: Export merchant private key

Step 8: Register merchant domains

SDK Installation​

Step 1: Include the library in your project​

3. Start a Transaction​

4. ContinuePayment​

5. Webhooks​

1. Generating a session

Request Body Params

Response Object

Payment Methods

2. Device Integration

2.1 Android (Google Pay)

Prerequisites

SDK Installation

Step 1: Include the library in your project

Step 2: Initialize the SDK with the public key

Step 3: Start the checkout process

Step 4: Start the payment process

2.2 iOS (Apple Pay)

Prerequisites

SDK Installation

Step 1: Include the library in your project

3. Start a Transaction

4. ContinuePayment

5. Webhooks