Initialize transaction

You can use this call to initialize a new Google Pay transaction.

Prerequisite

Get an access_token and use it as 'Bearer' token in your request. Find more details here.

Request

POST https://api.pay.cm.com/api/v1/paymentmethods/google-pay/v1/transactions/initialize

Request body examples

These are only some examples of the request body to create a transaction:

{
  "reference": "20210623130413",
  "description": "Order at yourdomain.tld",
  "amount": 1200,
  "currency": "EUR",
  "expiresAt": "2006-01-02T15:04:05Z",
  "language": "nl",
  "consumer": {
    "name": {
      "firstName": "John",
      "lastName": "Lopez",
      "middleName": "A"
    },
    "address": {
      "street": "Rustenburgerlaan",
      "houseNumber": "25",
      "postalCode": "2012AL",
      "city": "Haarlem",
      "countryCode": "NL",
      "state": "Noord-Holland",
      "additionalData": "Right-hand portal"
    },
    "email": "[email protected]",
    "businessName": "CM",
    "phone": "06-95613259",
    "gender": null,
    "dateOfBirth": "1996-12-01"
  },
  "webhooks": [
    {
      "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123",
      "events": [
        "FINALSTATUS"
      ]
    },
    {
      "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
      "events": [
        "REFUND_STATUS"
      ]
    },
    {
      "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
      "events": [
        "STATUS_CHANGE"
      ]
    }
  ],
  "returnUrls": {
    "success": "https://yourdomain.tld/order/payment-success.html",
    "cancelled": "https://yourdomain.tld/order/payment-cancelled.html",
    "expired": "https://yourdomain.tld/order/payment-expired.html",
    "failed": "https://yourdomain.tld/order/payment-failed.html"
  }
}
{
  "reference": "20210623130413",
  "description": "Order at yourdomain.tld",
  "amount": 1200,
  "currency": "EUR",
  "expiresAt": "2006-01-02T15:04:05Z",
  "language": "nl",
  "consumer": {
    "name": {
      "firstName": "John",
      "lastName": "Lopez",
      "middleName": "A"
    },
    "address": {
      "street": "Rustenburgerlaan",
      "houseNumber": "25",
      "postalCode": "2012AL",
      "city": "Haarlem",
      "countryCode": "NL",
      "state": "Noord-Holland",
      "additionalData": "Right-hand portal"
    },
    "email": "[email protected]",
    "businessName": "CM",
    "phone": "06-95613259",
    "gender": null,
    "dateOfBirth": "1996-12-01"
  },
  "webhooks": [
    {
      "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123",
      "events": [
        "FINALSTATUS"
      ]
    },
    {
      "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
      "events": [
        "REFUND_STATUS"
      ]
    },
    {
      "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
      "events": [
        "STATUS_CHANGE"
      ]
    }
  ],
  "returnUrl": "https://yourdomain.tld/order/payment-completed.html"
}
{
  "reference": "20210623130413",
  "description": "Order at yourdomain.tld",
  "amount": 1200,
  "expiresAt": "2006-01-02T15:04:05Z",
  "language": "nl",
  "returnUrl": "https://yourdomain.tld/order/payment-completed.html"
}

"Full Request with ReturnURLs" and "Full Request with ReturnURL" are examples where all the request parameters are provided. If returnUrls is defined then customers will be redirected to a different URL depending on the status of the transaction when the payment process is completed. If returnUrl is defined then customers will be redirected to the same URL no matter the status of the transaction when the payment process is completed.

"Minimal Request with ReturnURLs" is an example of the minimal request to create a transaction. This example, is using returnUrls, but you can replace it for returnUrl depending on what is better for your use case.

Parameters

ParameterTypeDescriptionConstraints
referenceString(1...255)An identifier specified by you. If webhooks were specified in the request this identifier is added to the webhook request payload.
descriptionString(1...255)Description of the transaction.
amountInt(1...99999999)Integer representing the amount of the transaction. Denomination in the smallest currency subunit (e.g. eurocents).
expiresAtString(RFC3339)Expiration time.ISO 8601 date and time.
languageString(ISO 639-1)Preferred language of the user interface.ISO 639-1 language.
returnUrlString(2000)Specifies the URL where your customers will be redirected to.Either returnUrl or returnUrls must be specified, but not both.
returnUrlsreturnUrls ObjectSpecifies a URL where your customers will be redirected to per transaction status. For example, your customers will be redirected to returnUrls.success when the status of the transaction changes to SUCCESS.Either returnUrl or returnUrls must be specified, but not both.

Optional parameters

ParameterTypeDescriptionConstraints
currencyString (ISO 4217)Currency code.ISO 4217 currency code.
consumerconsumer ObjectCustomer details.The following fields are mandatory: name.firstName, name.lastName, address.street, address.houseNumber, address.postalCode, address.city, address.countryCode, email.
webhooksArray of objectsWebhooks enable receiving a web request once a given event occurs.Find more details here.

Response

{
  "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  "orderId": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  "reference": "20210623130413",
  "amount": 1200,
  "currency": "EUR",
  "description": "Order at yourdomain.tld",
  "expiresAt": "2006-01-02T15:04:05Z",
  "language": "nl",
  "country": "NL",
  "webhooks": [
    {
      "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123",
      "events": [
        "FINALSTATUS"
      ]
    },
    {
      "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
      "events": [
        "REFUND_STATUS"
      ]
    },
    {
      "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
      "events": [
        "STATUS_CHANGE"
      ]
    }
  ],
  "status": "OPEN",
  "details": {
    "merchantCountry": "DE",
    "gatewayId": "example-gateway",
    "environment": "TEST",
    "merchantId": "exampleMerchantId",
    "merchantName": "www.example.com",
    "merchantKey": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
    "allowedCardNetworks": [
      "AMEX"
    ],
    "serverUrl": "https://www.example.com/api/"
  },
  "action": {
    "redirect": {
      "url": "https://checkout.tld/3ds/v2/creditcard/123"
    }
  },
  "createdAt": "2006-01-02T15:04:05Z",
  "refunds": {
    "refundedAmount": 300,
    "refundedPendingAmount": 100
  },
  "returnUrls": {
    "success": "https://yourdomain.tld/order/payment-success.html",
    "cancelled": "https://yourdomain.tld/order/payment-cancelled.html",
    "expired": "https://yourdomain.tld/order/payment-expired.html",
    "failed": "https://yourdomain.tld/order/payment-failed.html"
  }
}

Parameters

ParameterTypeDescriptionConstraints
idString(36)Transaction unique identifier.
orderIdString(36)Unique identifier.
referenceString(1...255)An identifier specified by you. If webhooks were specified in the request this identifier is added to the webhook request payload.Specified in the request.
amountInt(1...99999999)Integer representing the amount of the checkout. Denomination in the smallest currency subunit (e.g. eurocents).Specified in the request.
currencyString (ISO 4217)Currency code.Specified in the request.
descriptionString(1...255)Description of the transaction.Specified in the request.
expiresAtString(RFC3339)Expiration time.Specified in the request.
languageString(ISO 639-1)Preferred language of the user interface.Specified in the request.
countryStringCountry of the Customer.
statusStringOPEN - Transaction has been created. This is the initial status.
SUCCESS - Transaction successfully paid.
CANCELLED - Transaction has been cancelled by your customers.
EXPIRED - Transaction has not succeeded; expired.
FAILURE - Transaction has not succeeded; unknown reason.
AUTHORIZED - Transaction is authorized.
createdAtString(RFC3339)Creation time.ISO 8601 date and time.
returnUrlString(2000)Specifies the URL where your customers will be redirected to.Specified in the request.
returnUrlsreturnUrls ObjectSpecifies a URL where your customers will be redirected to per transaction status. For example, your customers will be redirected to returnUrls.success when the status of the transaction changes to SUCCESS.Specified in the request.

Optional parameters

ParameterTypeDescriptionConstraints
webhooksArray of objectsWebhooks enable receiving a web request once a given event occurs.Specified in the request.
detailsdetails ObjectThese are the details used to render the Google Pay button in your own page.This is nullable.
refundsrefund ObjectIndicates refundedAmount and refundedPendingAmount.

Response codes

HTTP statusDescription
201Transaction initialized.
4XXClient error response (See message for details). This response is given when the user input was incorrect or something illegal was attempted (eg. using a service without having that service configured for the user, or not being authorized).
5XXServer error response (See message for details).