--- title: "PayMe for API only" description: "Accept PayMe payments using our APIs, and build your own payment form." url: "https://docs.adyen.com/payment-methods/payme/api-only" source_url: "https://docs.adyen.com/payment-methods/payme/api-only.md" canonical: "https://docs.adyen.com/payment-methods/payme/api-only" last_modified: "2019-09-06T17:19:00+02:00" language: "en" --- # PayMe for API only Accept PayMe payments using our APIs, and build your own payment form. [View source](/payment-methods/payme/api-only.md) Depending on whether your shopper is using a desktop or laptop, or the browser on their mobile device: * Show the shopper a QR code which they can scan to pay using their PayMe app. * Redirect the shopper to the PayMe app on their mobile device. Implement both flows to make sure that your shoppers can pay on different devices. PayMe is supported from Checkout API version 67. ## Requirements | Requirement | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Make sure that you have built an [API-only integration](/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=API%20only). | | **Setup steps** | Before you begin, [add PayMe QR in your test Customer Area](/payment-methods/add-payment-methods). | ## Build your payment form for PayMe QR Include PayMe QR in the list of available payment methods. You do not need to collect any information from the shopper in your payment form. If you are using the [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) endpoint to show which payment methods are available to the shopper, specify in your request: * [countryCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods): **HK**. * [amount.currency](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods#request-amount): **HKD**. The response contains: * `paymentMethod.type`: **payme** We provide a PayMe QR logo which you can use on your payment form. For more information, refer to [Downloading logos](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%20only#downloading-logos). ## Make a payment When a shopper chooses to pay with PayMe QR, you need to redirect them to the PayMe QR app, depending on how they are accessing your site: * For shoppers on desktop or laptop, show a QR code. * For shoppers on mobile, present a button that redirects to the PayMe app. * For shoppers on tablet, you can show a QR code or a button that redirects to the PayMe QR app, or both. We recommend that you use screen size to determine whether the shopper is accessing your site on mobile, desktop, or tablet. ### Tab: Desktop flow Follow this flow to show the shopper a QR code on their desktop or laptop that they can scan to pay using their PayMe app. When the shopper selects to pay with , make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request with: | Parameter name | Required | Description | | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `paymentMethod.type` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **payme**. | | [returnUrl](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-returnUrl) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The URL where the shopper is redirected back to after completing the payment. | | [`channel`](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-channel) | | To determine whether the shopper is using a desktop, laptop or mobile. | | [`lineItems.quantity`](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-quantity) | | The number of items. Must be between 0 and 9999. | | [`lineItems.sku`](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-sku) | | The stock keeping unit. Maximum length 200 characters. Available if you use Checkout API v70 and later. | | [`lineItems.description`](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-description) | | The order description to display to the shopper. Maximum length 200 characters. | | [`lineItems.amountIncludingTax`](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-amountIncludingTax) | | Item amount including the tax, in minor units. Must be between 1 and 100000000. | | [`lineItems.itemCategory`](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems-itemCategory) | | The item category. Maximum length 200 characters. | Sample [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request: #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "paymentMethod": { "type": "payme" }, "amount": { "currency": "HKD", "value": 4200 }, "countryCode": "HK", "merchantAccount": "ADYEN_MERCHANT_ACCOUNT", "reference": "YOUR_ORDER_REFERENCE", "returnUrl": "https://your-company.example.com/...", "channel":"Web", "lineItems": [ { "quantity": "1", "sku": "3232", "description": "Shoes", "amountIncludingTax": 4200, "itemCategory": "Fashion" } ] }' ``` #### NodeJS (JavaScript) ```js // Set your X-API-KEY with the API key from the Customer Area. const {Client, Config, CheckoutAPI} = require('@adyen/api-library'); const config = new Config(); // Set your X-API-KEY with the API key from the Customer Area. config.apiKey = '[API_KEY]'; config.merchantAccount = '[MERCHANT_ACCOUNT]'; const client = new Client({ config }); client.setEnvironment("TEST"); const checkout = new CheckoutAPI(client); checkout.payments({ "paymentMethod": { "type": "payme" }, "amount": { "currency": "HKD", "value": 4200 }, "countryCode": "HK", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "reference": "YOUR_ORDER_REFERENCE", "returnUrl": "https://your-company.example.com/...", "channel":"Web", "lineItems": [ { "quantity": "1", "sku": "3232", "description": "Shoes", "amountIncludingTax": 4200, "itemCategory": "Fashion" } ] }) ``` The [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response contains: * `action.qrCodeData`: Use this to [render the QR code](#show-qr-code) on your checkout page. ```json { "resultCode": "Pending", "action": { "expiresAt": "2021-01-30T16:09:09Z", "paymentData": "Ab02b4c0!BQABAgCS3pcqSJK0PVsLw839", "paymentMethodType": "payme", "url": "https://qr.payme.hsbc.com.hk/...", "qrCodeData": "https://qr.payme.hsbc.com.hk/...", "type": "qrCode" } } ``` ## Show the QR code Follow these steps to render the QR code on your checkout page: 1. Use the `qrCodeData` from the `action` object to render the QR code on your checkout page. 2. After the shopper scans the QR code and completes the payment, we send a [webhook](/development-resources/webhooks) informing you of the payment result. 3. [Show the payment result to your shopper](#show-payment-result). When a shopper uses the browser of their mobile device, they are unable to scan the QR code. Request them to pay using their PayMe app by redirecting them to the `url` within the `action` object. You can recognise a shopper device using either the user-agent or the browser width parameter. ### Tab: Mobile flow Follow this flow to redirect the shopper from their mobile browser to the PayMe app. When the shopper selects to pay with , make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request with: * `paymentMethod.type`: **payme** * `returnURL`: The URL where the shopper is redirected back to after completing the payment. Sample [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request: #### curl ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "paymentMethod": { "type": "payme" }, "amount": { "currency": "HKD", "value": 4200 }, "countryCode": "HK", "merchantAccount": "ADYEN_MERCHANT_ACCOUNT", "reference": "YOUR_ORDER_REFERENCE", "returnUrl": "https://your-company.example.com/...", "channel":"Web", "lineItems": [ { "quantity": "1", "sku": "3232", "description": "Shoes", "amountIncludingTax": 4200, "itemCategory": "Fashion" } ] }' ``` #### NodeJS (JavaScript) ```js // Set your X-API-KEY with the API key from the Customer Area. const {Client, Config, CheckoutAPI} = require('@adyen/api-library'); const config = new Config(); // Set your X-API-KEY with the API key from the Customer Area. config.apiKey = '[API_KEY]'; config.merchantAccount = '[MERCHANT_ACCOUNT]'; const client = new Client({ config }); client.setEnvironment("TEST"); const checkout = new CheckoutAPI(client); checkout.payments({ "paymentMethod": { "type": "payme" }, "amount": { "currency": "HKD", "value": 4200 }, "countryCode": "HK", "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "reference": "YOUR_ORDER_REFERENCE", "returnUrl": "https://your-company.example.com/...", "channel":"Web/iOS/Android", "lineItems": [ { "quantity": "1", "sku": "3232", "description": "Shoes", "amountIncludingTax": 4200, "itemCategory": "Fashion" } ] }) ``` The [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response contains: ```json { "resultCode": "RedirectShopper", "action": { "expiresAt": "2021-01-30T16:09:09Z", "paymentMethodType": "payme", "url": "https://qr.payme.hsbc.com.hk/...", "method": "GET", "type": "redirect" } } ``` ## Handle the redirect 1. To complete the payment, redirect the shopper to the `action.url` returned in the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response, taking into account the following recommendations: * **When using the HTTP GET method:**\ For security reasons, when showing the redirect in the app, we recommend that you use [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller) for iOS or [Chrome Custom Tabs](https://developer.chrome.com/multidevice/android/customtabs) for Android, instead of WebView objects. Also refer to the [security best practices](https://developer.android.com/topic/security/best-practices#webview) for WebView. * **Redirection for mobile integrations:**\ For mobile integrations, we strongly recommended that you redirect the shopper to the default browser of their device. Redirecting to the default browser ensures the best compatibility, handling of multi-factor authentication, app-to-app redirection, and error handling. 2. After the shopper is redirected back to your website, check the payment result by making a POST [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) request, specifying: * `details`: object that contains the URL-decoded `redirectResult` returned when the shopper was redirected back to your site. **/payments/details request** ```bash curl https://checkout-test.adyen.com/v72/payments/details \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "details": { "redirectResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ==" } }' ``` 3. In the response note the following: * `resultCode`: use this to present the result to your shopper. * `pspReference`: our unique identifier for the transaction. **/payments/details response** ```json { "resultCode": "Authorised", "pspReference": "V4HZ4RBFJGXXGN82" } ``` ## Show the payment result Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details#responses-200-resultCode) that you received in the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response to show the payment result to your shopper. The `resultCode` values you can receive for PayMe are: | resultCode | Description | Action to take | | --------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Authorised** | The payment was successful. | Inform the shopper that the payment has been successful. | | **Cancelled** | The shopper cancelled the payment in the PayMe app. | Ask the shopper whether they want to continue with the order, or ask them to select a different payment method. | | **Pending** or **Received** | The shopper has completed the payment but the final result is not yet known. | Inform the shopper that you have received their order, and are waiting for the payment to be completed. To know the final result of the payment, wait for the [AUTHORISATION webhook](/development-resources/webhooks/webhook-types). | | **Refused** | The payment was refused by PayMe. | Ask the shopper to try the payment again using a different payment method. | []()If the shopper did not return to your website or app, wait for webhooks to know the outcome of the payment: | eventCode | success field | Description | Action to take | | ----------------- | ------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- | | **AUTHORISATION** | **false** | The transaction failed. | Cancel the order and inform the shopper that the payment failed. | | **AUTHORISATION** | **true** | The shopper successfully completed the payment. | Inform the shopper that the payment has been successful and proceed with the order. | ## Test and go live Use the PayMe sandbox to test your integration. You do not need to use the PayMe app to test using the sandbox. Use the amounts specified below to simulate different payment outcomes. | Amount ending in | Result | Description | | ---------------- | -------------- | ----------------------------------------------------------------------------- | | 30 or 81 | Authorised | Successful payment. | | 77 or 90 | OfferCancelled | The payment request expired after PayMe's default expiry time of ten minutes. | | 40 or 44 | Error | There was an error when creating the payment request. | ## See also * [API-only integration guide](/online-payments/api-only) * [Webhooks](/development-resources/webhooks) * [API Explorer](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/overview)