Integration Guide

Prerequisites

As a prerequisite, you should understand:

Process Details

Please ensure that this checklist has been fully completed before submission: Google Pay™ Integration Checklist

The payment process itself works similar to other payment methods. When one operates the Google Pay™ button, the payment instrument is chosen, and the necessary security checks are performed. The Google Pay API returns a security token, that must be handed over to authorise the payment against the secuconnect API. The secuconnect API methods to authorise and capture the payment are the same like for credit card payment, but there is a special Payment Container type for Google Pay™.

To set up for live transactions, you need two merchant IDs. One is received from Google (merchantId), the other from the secupay (gatewayMerchantId). You can receive the Google merchant ID, and request production access for particular Internet domains, at https://developers.google.com/pay/api/web/guides/test-and-deploy/request-prod-access.

Google Pay™ Button Integration

The Google Pay™ button integration is described in the Google Pay Web developer documentation at https://developers.google.com/pay/api/web/overview.

The following details are fix. Our JavaScript excerpt shows the details required by us:

Excerpt from JavaScript button integration

/**
 * You must use API version 2.0
 */
const baseRequest = {
  apiVersion: 2,
  apiVersionMinor: 0
};
 
/**
 * The supported card networks depend on your contract. You will recevive the exact settings from secupay.
 */
const allowedCardNetworks = ["AMEX", "DISCOVER", "MASTERCARD", "VISA"];
 
/**
 * The supported authentication methods depend on your contract. You will recevive the exact settings from secupay.
 *
 * With new contracts, both modes are supported. Old contracts support only "CRYPTOGRAM_3DS".
 * 
 * If you offer "PAN_ONLY", then you need to implement the 3-D Secure process described below (s. Authorize the Payment)
 */
const allowedCardAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];
 
/**
 * You must use type 'PAYMENT_GATEWAY'. The exact parameters for gateway and gatewayMerchantId depend on the contract.
 *
 * For new contracts, you must use the gateway 'secupay'. The gatewayMerchantId must be the GCR_xyz contract ID for the Internet domain, and the same used to create the Smart Transaction later.
 */
const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'secupay',
    'gatewayMerchantId': 'GCR_674YDN6G8R2LP0VMC7P9TE877MUUGZ'
  }
};
 
/**
 * You must use type 'CARD'.
 */
const baseCardPaymentMethod = {
  type: 'CARD',
  parameters: {
    allowedAuthMethods: allowedCardAuthMethods,
    allowedCardNetworks: allowedCardNetworks
  }
};
 
/**
 * You must use the merchant ID received from Google Pay here. The merchant name is optional.
 */
function getGooglePaymentDataRequest() {
    // ...
    merchantId: '8S1DOIRYLUXU3M11',
    merchantName: 'Musterhändler GmbH',
    // ...
}
 
// ...

Obtaining the Button Parameters Dynamically

This is only needed for more flexible platform integrations.

For a single merchant integration, the parameters for the Google Pay™ button can be hard-coded. We will inform you in time, when something needs to be changed.

For more flexible solutions, you can retrieve the settings dynamically from our Iframe options endpoint. You need to call GET General/Contracts/GCR_xxx/IframeOptions, where GCR_xxx is the merchant's contract ID for the particular domain:

Request

GET /api/v2/General/Contracts/GCR_674YDN6G8R2LP0VMC7P9TE877MUUGZ/IframeOptions HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

Among other details, it will return the Google Iframe options available for the contract:

Response (Excerpt)

HTTP/1.1 200 OK
Host: connect-testing.secuconnect.com
Content-Type: application/json
{
  "payment_config": {
    "Googlepay": {
      "allowed_auth_methods": [
        "CRYPTOGRAM_3DS",
        "PAN_ONLY"
      ],
      "allowed_card_networks": [
        "MASTERCARD",
        "VISA"
      ],
      "gateway": "secupay",
      "gateway_merchant_id": "GCR_674YDN6G8R2LP0VMC7P9TE877MUUGZ"
      "merchant_name": "Musterhändler GmbH"
    },
  }
}

Details of payment_config/Googlepay explained:

Parameter	Type	Meaning
`allowed_auth_methods`	`array`	All authentication methods that will work with this contract. Either `CRYPTOGRAM_3DS` or both, `CRYPTOGRAM_3DS` and `PAN_ONLY`. Passed on unchanged to `allowedAuthMethods` for the Google Pay™ button. You may only pass `CRYPTOGRAM_3DS` in order to save the implementation of the 3-D Secure redirect. But the Google Pay™ will not be offered on many devices.
`allowed_card_networks`	`array`	All card networks available with this contract. Passed on unchanged to `allowedCardNetworks` for the Google Pay™ button. You may pass fewer options than allowed, if you would not like to offer all networks. But you must not offer more networks than returned.
`gateway`	`string`	Passed on unchanged as `gateway` for the Google Pay™ button. Note: This value can change when contracts are changed. For older contracts it is not `secupay`.
`gateway_merchant_id`	`string`	Passed on unchanged as `gateway_merchant_id` for the Google Pay™ button. Note: Currently this value is always the contract ID of the request.
`merchant_name`	`string`	The merchant name associated with the contract. Optionally passed on as `merchant_name` for the Google Pay™ button. You may also pass another spelling of the name from your application or use the default that is configured in the Google Pay™ configuration.

Authorise the Payment

In order to authorise the Smart Transaction for Google Pay™ payment, you need to call POST Smart/Transactions/STX_xxx/prepare/creditcard:

Request

POST /api/v2/Smart/Transactions/STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2/prepare/creditcard HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "customer": {
        "contact": {
            "forename": "Mike",
            "surname": "Mustermann",
            "name": "Mike Mustermann",
            "address": {
                "street": "Musterstr.",
                "street_number": "42",
                "additional_address_data": "Whg. 103",
                "postal_code": "09999",
                "city": "Musterstadt",
                "country": "DE"
            },
            "email": "mike@example.net",
            "mobile": "+491775555555",
            "phone": "+495555555555"
        }
    },
    "merchant": {
        "id": "MRC_FDFCR9PP93SOINGJ7F63WKBHMFVW2O"
    } 
    "container": {
        "type": "googlepay",
        "private": {
            "protocolVersion": "ECv2", 
            "signature": "MEUCIGXzEMNUb5GCEG7AuMYod8ofOf/McdVJxobWyj7hq60JAiEAinmOEw6tPgKXEoN4jFpxwdXwHgie4HTtg5b2kfrjC4M\u003d",
            "intermediateSigningKey": {
                "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEd8INiTXkwHuWx0RUxzMvVaxaOldLrU9FZHD5i5awPtFxJcfPJhb7x0DNPLCCXdtGpeILckeEHWZJhwTSjn//YQ\\u003d\\u003d\",\"keyExpiration\":\"1689146771378\"}",
                "signatures": [
                    "MEQCICj3uiUDhAZUXUFtRm0aAWYAURoukH1h+fDJ+SzzLq/rAiA2jgCQCCJs7HG6pcwQOoWgRxf3TzNaRvEJbiG1WNmYJg\u003d\u003d"
                ]
            },
            "signedMessage": "{\"encryptedMessage\":\"8u7d/X9xXb0QE9Vqu6QeJwqQAwbXaVByPJKn0ZOqwUFh+PRgjxD7Hma6VOEIkB0Pnox6n+8x4CuDdxkhI+33qbDJm73G0AVHXK5KMJDB82i/RWjxN57y0SwVrYIUjYk1M43zew78kuslGHRKGUGFVoL/3IogvifQmMkiPh+G/Teu1QHVPhUKJoPAbotCWx9/FLs8GYwRUec2+MAXxN/iL3Wp/I0pY8PoM72OJEBB5+jASzqzFeYlXBsjVzw0wyfvcl8Komno0p3sgHPg4ZfA3OdCFPgESfGTY5Gg1C3PzVS40u8RkBNSM6MQbkgqOvzb0nOOUEhY+hJbjhaI1kH3xlxueRxvXIYZIe9ZuzECeDi+Eu6MwdtI3Q+genqkJbcpNmnCUQE3nfRPGldB8c2+AZVG9plg3gCRqSR0nai8j54MDxrT1fvRvelgEPH1E1hi+1xHfDa9nzsDkR1wJWbJp2WZtE8PR6m9swdW\",\"ephemeralPublicKey\":\"BEaKyKbKHyOLjUDr6pFnGHFc1196gGx9U8nKAfIinw8V6KXNZCmdOTnxRNrZUdW+byZAapX1ntYFEDtciDQuwvI\\u003d\",\"tag\":\"B0qC1vdOqWg8ZOP16pS7oSJG4+hjBXGs9QljYByyJm8\\u003d\"}"
        }
    },
    "callback_urls": {
        "success_url": "https://shop.example.com/payment/success?nonce=ciix8j3qbqffg8dcdc7b",
        "failure_url": "https://shop.example.com/payment/failure?nonce=ciix8j3qbqffg8dcdc7b"
    }
}

These are the parameters:

Parameter	Type	Meaning
`container`	`object`	Payment container data
`container/type`	`string`	Always `"googlepay"` for this payment method
`container/private`	`object`	Data taken from Google Pay token (`paymentData.paymentMethodData.tokenizationData.token`)
`customer`	`object`	Customer. Only needed if not set before.
`customer/id`	`string`	Customer ID (`PCU_xxx`)
`merchant`	`object`	Merchant. Only needed if not identified by the contract.
`merchant/id`	`string`	Merchant ID (`MRC_xxx`)
`callback_urls`	`object`	Return URLs for 3-D Secure check; only needed for method `"PAN_ONLY"`
`callback_urls/success_url`	`string`	Return URL for successful authentication
`callback_urls/failure_url`	`string`	Return URL for failed or aborted authentication

The two callback URLs are needed to return the customer to your checkout after succeeded or failed 3-D Secure check. Whether a 3-D Secure check is needed, can be recognised by the API response.

If you have any questions about these details, please ask our friendly help desk.

In the best case, the Smart Transaction is authorised immediately:

Response (3-D Secure Not Required)

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "smart.transactions",
    "id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
    // ...
    "customer": {
        "object": "payment.customers",
        "id": "PCU_WZ3HENRNE2NSQMSQHRD58CPH7GHCA2",
        "contact": {
            "forename": "Mike",
            "surname": "Mustermann",
            "name": "Mike Mustermann",
            "address": {
                "street": "Musterstr.",
                "street_number": "42",
                "additional_address_data": "Whg. 103",
                "postal_code": "09999",
                "city": "Musterstadt",
                "country": "DE"
            },
            "email": "mike@example.net",
            "mobile": "+491775555555",
            "phone": "+495555555555"
        }
    },
    "container": {
        "object": "payment.containers",
        "id": "PCT_SF9XGHPVC2NSQX03V86EREAMMET7AZ"
    },
    // ...
    "transactions": [
        {
            "object": "payment.transactions",
            "id": "PCI_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7"
        }
    ],
    "created": "2020-10-29T14:13:41+01:00",
    "updated": "2020-10-29T14:13:50+01:00",
    "status": "approved",
    // ...
    "payment_method": "creditcard",
    "trans_id": "30093721",
    // ...
}

This means, no 3-D Secure check is needed.

Status approved means the payment is authorised and you should be able to capture it. Status failed means you must repeat the payment process. You must also repeat the payment process when you update the Smart Transaction. It is then set back to created.

If the option auto_capture is true, it would already capture the Smart Transaction. Status ok, received or collection means you can deliver. Status pending means you have to wait for one of these statusses. Status failed means the payment failed, and you must repeat the payment process.

The following variant with 3-D Secure does not occur when only "CRYPTOGRAM_3DS" is used.

In case a 3-D Secure check is needed, the status stays unchanged (created or with loyalty probably processing), and an iframe URL is added to the Smart Transaction:

Response (3-D Secure Required)

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "smart.transactions",
    "id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
    // ...
    "customer": {
        "object": "payment.customers",
        "id": "PCU_WZ3HENRNE2NSQMSQHRD58CPH7GHCA2",
        "contact": {
            "forename": "Mike",
            "surname": "Mustermann",
            "name": "Mike Mustermann",
            "address": {
                "street": "Musterstr.",
                "street_number": "42",
                "additional_address_data": "Whg. 103",
                "postal_code": "09999",
                "city": "Musterstadt",
                "country": "DE"
            },
            "email": "mike@example.net",
            "mobile": "+491775555555",
            "phone": "+495555555555"
        }
    },
    "container": {
        "object": "payment.containers",
        "id": "PCT_SF9XGHPVC2NSQX03V86EREAMMET7AZ"
    },
    "transactions": [
        {
            "object": "payment.transactions",
            "id": "PCI_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7"
        }
    ],
    "created": "2020-10-29T15:53:11+01:00",
    "updated": "2020-10-29T15:53:25+01:00",
    "status": "created",
    // ...
    "payment_method": "creditcard",
    "trans_id": "30093750",
    "iframe_url": "https://securepay.epayworldwide.com/securepay/pay.php?TID=93999999&IDENT=93999999_2910...",
    // ...
}

In this case you have to offer the customer the iframe_url. He will then go through the 3-D Secure process.

Despite its name, you should not open the iframe_url within an Iframe (<iframe>):

3-D Secure checks can leave the Iframe and switch to full-screen. In this case, the success (success_url) or failure URL (failure_url) of the shop is not opened inside the Iframe, but in the uppermost browser window (DOM window.top).
Some popular browsers have very strict same-origin restrictions for third party content, so that Cookie technology will not work inside Iframes. Most external authorisation flows cannot be completed.

In case you would also like to offer Sofort, please note that such payments are not allowed in Iframes at all.

After the 3-D Secure process the customer is either directed back to the success_url or failure_url you have passed when calling /prepare. When the success_url is called, the Smart Transaction can be expected to have status approved now. You can proceed to start the Smart Transaction and capture the payment. If auto_capture is set, the payment is already captured, and the Smart Transaction has either status ok, received or collection.

When the failure_url is called, you need to repeat the payment process.

You can ask our help desk to change the contract settings for demo transactions, so that you can test either with 3-D Secure or without.

Capture the Payment

The way to capture an authorised payment is the same for all payment methods. If you have already studied this for invoice or direct debit payment, you will not find any new details.

Usually you you would use "auto_capture": true, and it is not necessary to make this extra call.

When you implement invoice payment, you must use an additional call to mark the payment as due, and to capture the Payment Transaction.

In order to start the authorized Smart Transaction, you only need to call POST Smart/Transactions/STX_xxx/start.

Request

POST /api/v2/Smart/Transactions/STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2/start HTTP/1.1
Host: connect-testing.secuconnect.com
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Accept: application/json

If everything is fine, the API responds with 200 OK:

Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "object": "smart.transactions",
    "id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
    // ...
    "transactions": [
        {
            "object": "payment.transactions",
            "id": "PCI_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7"
        }
    ],
    "created": "2020-03-27T10:55:23+01:00",
    "updated": "2020-03-27T10:56:41+01:00",
    "status": "ok",
    // ...
}

Status ok, received or collection means you can deliver. Status pending means you have to wait for one of these statusses. Status failed means the payment failed, and you must repeat the payment process.

Integration Guide

Pay with Google Pay™

Prerequisites

Process Details

Google Pay™ Button Integration

Obtaining the Button Parameters Dynamically

Authorise the Payment

Capture the Payment

See Also