> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dintero.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.dintero.com/feedback
```json
{
"path": "/docs/checkout/google-pay/google-pay-native-app",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Native app integration
> Integrate Google Pay directly in your Android app or website with Dintero PSP processing the payment and your code controlling the Google Pay UI.
Native app integration gives you complete control over the Google Pay user experience within your mobile application or website. While Dintero handles the payment processing, you implement the Google Pay interface directly, providing a seamless experience for your customers.
Native app integration with Google Pay is supported only via `dintero_psp.googlepay`. If you are using Worldline (`bambora.googlepay` in the API), native app integration is not available.
### Prerequisites
#### Google Pay Merchant Onboarding
Before implementing Google Pay in your app, you must complete Google's merchant onboarding process:
1. Create a [Google Pay API developer account](https://pay.google.com/business/console)
2. Complete Google's merchant verification process
3. Submit your integration for Google's review and approval
4. Receive approval to process live transactions
**Note**: This process can take several weeks, so plan accordingly. You can begin development using Google's sandbox environment while awaiting approval.
#### Enable Google Pay on your Dintero account
During your onboarding, Google Pay will generally be enabled as a payment method by default. If it's not
enabled, you can go to settings and payment methods. There you can enable Google Pay as a payment method for your
account. If you use [payment profiles](https://docs.dintero.com/docs/checkout/payment-profiles) ensure that
Google Pay is added to the relevant profiles.
### Integration with Dintero
Below we'll describe how you can implement the payment flow yourself. The flow is as follows:
1. User initiates payment
2. You request payment data from Google Pay
3. Google Pay returns the payment data
4. You post the payment data to Dintero
5. If required, you ask user to perform 3-D Secure challenge
6. You initiate the payment
```mermaid theme={null}
sequenceDiagram
actor C as Customer
participant A as Your app
participant GP as Google Pay
participant DC as Dintero Checkout
participant DPS as Dintero PSP Service
participant 3DS as 3-D Secure
C->>A: User initiates payment
A->>GP: Request payment data
GP-->>A: Payment data
A->>DC: Post payment data
DC-->>A: Auth methods
opt If 3-D Secure is required
A->>3DS: Open hosted 3DS solution using in-app web ui
3DS-->>C: Present challenge to customer
C->>3DS: Complete 3DS challenge
3DS-->>DPS: Notify Dintero about 3DS result
DPS-->>A: Redirect to app with 3DS result
end
A->>DC: Initiate checkout payment
DC-->>A: Payment result
```
#### Dintero API
[create a session]: /docs/checkout/create-session
[payment in app]: /docs/checkout/payment-in-app
To integrate directly with Dintero you can use the Checkout API, see the [API reference](/checkout-api.html).
To enable payments with Dintero you first need to [create a session] with Dintero. Also see how you can configure
your session for [payment in app].
Once you have a session you can get [payment operations](/checkout-api.html#operation/checkout_sid_payments_product_type_post). For Google Pay, you want to
get the operation with a rel of `submit-dintero-psp-googlepay`. This operation will contain the endpoint to use for submitting the
Google Pay payment data, as well as the fields you need to configure Google Pay:
* `supported_networks`: The supported networks for Google Pay
* `gateway_merchant_id`: This is your gateway merchant ID, which is your account ID. In production this should start with a `P`, in test mode it should start with a `T`
* `gateway_id`: The gateway ID to use, this will always be `dintero`
* `googlepay_merchant_id`: For native implementation you should ignore this field
* `href`: This is the URL you should post the Google Pay payment data to
Example request (note, there is no body or content type in this POST request):
```
POST https://checkout.dintero.com/v1/view/{session_id}/payments/dintero_psp.googlepay
```
```json theme={null}
{
"operations": [
{
"href": "https://payments.psp.dintero.com/google-pay/v1/{account_id}/payments/{payment_id}/transactions?access_token={access_token}",
"method": "POST",
"rel": "submit-dintero-psp-googlepay",
"content_type": "application/json",
"googlepay_merchant_id": "{googlepay_merchant_id}",
"supported_networks": [
"VISA",
"MASTERCARD"
],
"gateway_id": "dintero",
"gateway_merchant_id": "{gateway_merchant_id}"
}
]
}
```
#### Setting up Google Pay
See the [Google Pay Android overview](https://developers.google.com/pay/api/android/overview) for an overview of how it works, the payment flow, and various resources.
You can follow the [tutorial from Google Pay](https://developers.google.com/pay/api/android/guides/tutorial) to configure Google Pay for Android.
Below we'll describe some of the steps for configuring Google Pay, specifically which values to use and where to find them.
##### Gateway ID and Gateway Merchant ID
Set the gateway and gateway merchant ID to ensure you use Dintero as the gateway.
The gateway should always be `dintero` and will be returned in `gateway_id`. The gateway merchant ID is returned in `gateway_merchant_id`
and should be your account ID.
```kotlin theme={null}
private fun gatewayTokenizationSpecification(): JSONObject {
return JSONObject().apply {
put("type", "PAYMENT_GATEWAY")
put("parameters", JSONObject(mapOf(
"gateway" to "dintero",
"gatewayMerchantId" to "YOUR_DINTERO_ACCOUNT_ID")))
}
}
```
Replace `YOUR_DINTERO_ACCOUNT_ID` with your actual Dintero account ID. The correct value is returned as `gateway_merchant_id` in the payment operation. You can also find your account ID by logging in to [Backoffice](https://backoffice.dintero.com/), where it will be displayed in the upper right corner. It is an 8-digit number with a preceding P or T (e.g., P12345678). Use PXXXXXXXX for production and TXXXXXXXX for testing (e.g., when in test mode).
##### Authorization Methods
Google Pay can provide both cards on file (`PAN_ONLY`) or device tokens (`CRYPTOGRAM_3DS`). Device tokens are tokens bound to an Android device that is authenticated with a 3-D Secure cryptogram. Dintero supports both methods.
Device tokens will generally not require 3-D Secure authentication as they are already authenticated, while `PAN_ONLY` will generally require 3-D Secure authentication.
For native apps it is recommended to at least use `CRYPTOGRAM_3DS`. To support both methods for maximum compatibility you can do the following:
```kotlin theme={null}
private val allowedCardAuthMethods = JSONArray(listOf(
"PAN_ONLY",
"CRYPTOGRAM_3DS"))
```
##### Card Networks
You have to provide the card networks that you want to accept to Google Pay. While you can choose to not support all card networks, you should not provide any networks not supported by Dintero.
The card networks supported by Dintero are returned as `supported_networks` in the payment operation.
```kotlin theme={null}
private val allowedCardNetworks = JSONArray(listOf(
"MASTERCARD",
"VISA"))
```
##### Submitting Payment Token
Once everything is configured you can request a payment token from Google as described in their [tutorial](https://developers.google.com/pay/api/android/guides/tutorial).
You should then receive the [payment data](https://developers.google.com/pay/api/web/reference/response-objects#PaymentData) that you should submit to Dintero. Use the `href`
returned in the [payment operations](/checkout-api.html#operation/checkout_sid_payments_product_type_post) for the `submit-dintero-psp-googlepay` operation,
see the [API reference](/psp-wallet-api.html#operation/googlePayPost_Google_Pay_Transaction)
Extract the `access_token` query parameter from the operation `href` and post the payment data. Please remove the `access_token` query param from the URL before posting payment data. Ensure you send the `payment_data` as a JSON string.
```
POST https://payments.psp.dintero.com/google-pay/v1/{account_id}/payments/{payment_id}/transactions
Authorization: {access_token}
Content-Type: application/json
Body:
{
"reference": "{unique id}",
"payment_data": "{Google Pay payment data}"
}
```
Example response body where 3-D Secure is not needed, your application can continue to the initiate checkout payment step.
```json theme={null}
{
"payment_id": "{payment_id}",
"transaction_id": "{transaction_id}",
"auth_method": {
"type": "NONE",
"payment_id": "{payment_id}",
"transaction_id": "{transaction_id}"
},
"operations": []
}
```
Example response body where 3-D Secure is required, your application will have to show a web UI where the customer can complete 3-D Secure.
```json theme={null}
{
"payment_id": "{payment_id}",
"transaction_id": "{transaction_id}",
"auth_method": {
"type": "SECURE_3D_AUTHENTICATION",
"payment_id": "{payment_id}",
"transaction_id": "{transaction_id}"
},
"operations": [
{
"href": "{url_to_hosted_3ds_session}",
"method": "GET",
"rel": "3d-secure-init-hosted"
}
]
}
```
##### 3-D Secure
You need to support performing 3-D Secure authentication even if you only support device tokens, as there can be instances where additional authentication is required.
##### Performing 3-D Secure
The response when you post payment data will let you know if you need to perform 3-D Secure or not. If `auth_method.type` is `NONE` there should be no need for 3-D Secure,
otherwise you need to find the operation with a `rel` of `3d-secure-init-hosted` and open the provided URL in an iframe.
When the user has completed 3-D Secure you will receive a redirect back to the return URL used for the payment session.
The redirect will contain a query parameter `status_3ds` with a value indicating the result of the 3-D Secure challenge: `3DS_SUCCESS`, `3DS_FAILURE`, or `3DS_CANCEL`.
When 3-D Secure is finished you can continue and initiate the checkout payment.
##### Initiate Checkout Payment
After posting the Google Pay payment data to Dintero and performing 3-D Secure (if required), the next step is to [initiate the checkout payment](/checkout-api.html#operation/checkout_sid_pay_post).
Make sure you set the `payment_product_type` to `dintero_psp.googlepay`. The `psp_transaction_id` will be returned when you submit the payment token data to Dintero.
```
POST https://checkout.dintero.com/v1/sessions/{session_id}/pay
Content-Type: application/json
Body:
{
"payment_product_type": "dintero_psp.googlepay",
"psp_transaction_id": "{transaction_id}"
}
```
After posting to the initiate checkout payment endpoint the payment session is completed and has created an authorized transaction. The payment response will contain a `return_url` but there is no
need to follow or call it.
### Testing
#### Sandbox Environment
You can use Google Pay's test environment during development to test your integration. Ensure you use the correct account ID when in test mode (it should start with a T).
Test amounts for triggering errors:
* 401: Soft declined.
* 5XX: If amount starts with 5, the two last digits will be the response code from Dintero
* 501: Response code 01.
* 502: Response code 02.
* etc.
The test payments will not charge any cards.
Make sure to verify that you handle 3-D Secure and handle the redirect correctly.
#### Production Testing
Once you are ready to test in production you can enable Google Pay for production and try payments.
Note that this will actually charge your card, but you can cancel or refund the payment after testing.
If you want to avoid exposing Google Pay to customers while testing in production you can set up a
[payment profiles](https://docs.dintero.com/docs/checkout/payment-profiles) and add Google Pay
to a profile that isn't used for customers.
### Best Practices
Make sure you follow the following best practices.
* Never log or store Google Pay tokens
* Implement proper error handling to avoid exposing sensitive information
* Validate all payment responses on your server
### Example application
See [https://github.com/Dintero/dintero-android-native-example](https://github.com/Dintero/dintero-android-native-example) for an example application on how to accept Google Pay payments.
## Troubleshooting
### Common Issues
* Ensure you have configured Google Pay with your own Google Pay merchant ID
* Verify gatewayMerchantId matches your Dintero account
* Check that Google Pay is enabled in your Dintero account
* Ensure proper authorization method configuration
* Ensure Google Pay is not configured with networks not supported by Dintero
#### More resources
* [Google Pay on Android](https://developers.google.com/pay/api/android)
* [Google Pay integration checklist](https://developers.google.com/pay/api/android/guides/test-and-deploy/integration-checklist)
* [Google Pay brand guidelines](https://developers.google.com/pay/api/android/guides/brand-guidelines)
* [Dintero Checkout API](/checkout-api.html)
* [Test cards](/docs/checkout/testdata/dintero-psp/checkout-dintero-cards-testdata)