Skip to main content
This guide shows how to add Paze to a native iOS or Android app. The shopper completes the Paze flow in your app via the Paze mobile SDK, and your server uses the Gr4vy server SDK to orchestrate the session and create the resulting transaction. For background on how Paze works and how Gr4vy fits in, read the overview. A runnable web simulation of this flow is available in the sample-standalone-paze repository, alongside the web version. The repository shows the server-side calls end-to-end against the Gr4vy API; pair it with the Paze iOS or Android SDK in your own app for the native launch step.

​
Before you begin

Each merchant that wants to use Paze needs to be approved by Early Warning Services (EWS), and Gr4vy then enables Paze on a per-merchant basis. To start onboarding, see Set up Paze on the connector page. The native Paze iOS and Android SDKs are distributed by Paze. Your Paze onboarding contact provides the SDK, the integration documentation, and the credentials your app needs.
The server-side examples assume you have already created a Gr4vy client authenticated with your private API key. See Authentication to create the client. Keep your API key and the Gr4vy client on the server — never expose them in your mobile app.

​
Overview of the flow

The mobile integration has a server side and an app side that coordinate through a callback URL:
  1. Server-side — create a Paze mobile session with Gr4vy. The session returns the Paze merchant data id, name, profileId, an accessToken, and a sessionId.
  2. Server-side — create a Paze checkout URL with the session values, your callback URL scheme, and the intent.
  3. App-side — launch the Paze checkout URL using the Paze iOS or Android SDK. After the shopper finishes, Paze invokes your callback URL scheme with an opaque response code.
  4. App-side — forward the response code to your server.
  5. Server-side — (optional) review the session. Required for REVIEW_AND_PAY if you want Gr4vy to add shipping details to the transaction; skipped for EXPRESS_CHECKOUT.
  6. Server-side — complete the session to get the opaque token.
  7. Server-side — create a Gr4vy transaction with the token.

​
Step 1: Create a Paze mobile session

On your server, create a Paze session with source set to "mobile". Unlike the web flow, domain_name is not required for mobile sessions. The response includes the merchant id, name, profileId, plus the accessToken and sessionId you pass to the next step. 
var res = await client.DigitalWallets.Sessions.PazeAsync(
    pazeSessionRequest: new PazeSessionRequest()
    {
        Source = "mobile",
    }
);

PazeMobileSession? session = null;
if (res?.Type == ResponseCreatePazeDigitalWalletSessionType.PazeMobileSession)
{
    session = res.PazeMobileSession;
}
Use the same accessToken and sessionId for every server call in this checkout (create, review, complete). Do not reuse them for a different checkout — request a new session each time.
Response
{
  "id": "W8GT9RLCNME754Z7025613H3PDM2T4HF2CSAOi9w2kkP3D4S0",
  "name": "ACME",
  "profileId": "550e8400-e29b-41d4-a716-446655440000",
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sessionId": "7c1cba03-d20e-4a3f-9d77-e5dc23a39ac2"
}

​
Step 2: Create the Paze checkout URL

Call paze_mobile_session_create with the values from Step 1, the callback URL scheme your app handles, the intent, and the transaction value. The response includes a pazeCheckoutUrl to open in the Paze SDK. The supported intents are:
  • REVIEW_AND_PAY — the shopper reviews shipping and card details before paying. Your app and server then call the review step before completing.
  • EXPRESS_CHECKOUT — the shopper pays immediately without a review step.
var create = await client.DigitalWallets.Sessions.PazeMobileSessionCreateAsync(
    pazeMobileSessionCreateRequest: new PazeMobileSessionCreateRequest()
    {
        Client = new PazeClient() { Id = session.Id, Name = session.Name, ProfileId = session.ProfileId },
        SessionId = session.SessionId,
        AccessToken = session.AccessToken,
        CallbackURLScheme = "myapp://paze/return",
        Intent = "REVIEW_AND_PAY",
        TransactionValue = new PazeTransactionValue()
        {
            TransactionAmount = "50.21",
            TransactionCurrency = "USD",
        },
        TransactionType = "PURCHASE",
    }
);
Return create.pazeCheckoutUrl, session.sessionId, and session.accessToken to your app, along with the chosen intent. Your app needs all three to handle the callback and call your server again in Step 4.

​
Step 3: Launch Paze in your app

Use the Paze iOS or Android SDK to open pazeCheckoutUrl. The exact native call is specific to each platform — refer to the SDK documentation your Paze onboarding contact provides. When the shopper finishes, Paze invokes your callback URL scheme (the one you passed in Step 2) with a response parameter containing a base64-encoded JWE. Your app decodes that value and sends it to your server, together with the sessionId, accessToken, and intent from Step 2. See sample-standalone-paze for an end-to-end reference of the callback decode and the server-side review/complete/transaction calls.
The callback response is sensitive material that authorizes the transaction. Forward it directly to your server over a trusted channel — do not persist it client-side or send it to other destinations.

​
Step 4: Review the session

This step is optional. Call paze_mobile_session_review when you want Gr4vy to add the shipping address (and the rest of the review data) to the transaction in Step 6. Skip it for EXPRESS_CHECKOUT, or for REVIEW_AND_PAY checkouts where you do not need those details — and pass the original callback code directly to Step 5. Call paze_mobile_session_review with the JWE code from the callback. The response includes the selected card (masked), the consumer, and the shipping address. When you call review, use review.code as the input to Step 5. 
var review = await client.DigitalWallets.Sessions.PazeMobileSessionReviewAsync(
    pazeSessionReviewRequest: new PazeSessionReviewRequest()
    {
        SessionId = sessionId,
        Code = code,
        AccessToken = accessToken,
    }
);

​
Step 5: Complete the session

Call paze_mobile_session_complete with the code from the previous step (review.code for REVIEW_AND_PAY, or the original callback code for EXPRESS_CHECKOUT). The response includes completeResponse, the opaque token you forward to Gr4vy as the transaction token. 
var complete = await client.DigitalWallets.Sessions.PazeMobileSessionCompleteAsync(
    pazeSessionCompleteRequest: new PazeSessionCompleteRequest()
    {
        SessionId = sessionId,
        Code = completeCode,
        AccessToken = accessToken,
        TransactionType = "PURCHASE",
    }
);

​
Step 6: Create a transaction

Create the transaction with the opaque completeResponse from Step 5 as token. Set checkout_token to the original JWE callback code from Step 3 (not review.code) so Gr4vy can populate the masked card details and shipping address on the transaction.
The Paze mobile SDK and transactionValue use decimal-string major units (for example "50.21"), while Gr4vy’s transaction amount is an integer in the smallest currency unit (for example 5021 for $50.21). Convert between the two when bridging the values, and make sure they match for the same purchase.
var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 5021,
        Currency = "USD",
        Country = "US",
        PaymentMethod = TransactionCreatePaymentMethod.CreatePazePaymentMethodCreate(
            new PazePaymentMethodCreate()
            {
                Method = "paze",
                Token = complete.CompleteResponse,
                CheckoutToken = code,
            }
        ),
    }
);
The response is a standard Gr4vy transaction. Handle its status as you would for any other payment method.

​
Test Paze

To test Paze on mobile, drive your integration in a simulator or device build with a Paze test wallet.
Test wallet credentials are issued by Paze, not by Gr4vy. To obtain a test wallet for your merchant, work with Paze directly through your Paze onboarding contact.
For general sandbox environment information, see Paze’s Environments guide.