Page Summary
-
All API communication is conducted via HTTP POST, with JSON-serialized, encoded, and PGP-encrypted payloads in the request and response bodies.
-
Clients must encrypt and sign JSON bodies using PGP, web-safe base64 encode the payload, and can utilize multiple PGP keys for both signing and encrypting a single request.
-
The server is required to verify that every incoming request is signed with Google's private PGP key.
-
The server API must be an HTTPS endpoint, using a certificate from the Mozilla CA certification program and supporting TLS 1.2 or higher.
-
The server must use a root certificate included in the Mozilla CA certification program and the certificate should not be revoked, and common name (CN) checking must be turned on for the server's certificate.
API call flow
Success flow
KYC flow
eMandate flow
Application state vs APIs
API Security
Encryption
All communication uses HTTP POST. The POST and response bodies is JSON serialized, encoded and encrypted using PGP.
PGP is a standard set of encryption, decryption, and signing algorithms, which provide cryptographic privacy and authentication. In many areas of this spec, communication is either PGP encrypted, PGP signed, or both.
The payment integrator must support:
- Encrypting and decrypting payloads with multiple PGP keys.
- Signing payloads with multiple PGP keys.
- Verifying a payload with multiple signatures, any one of which can be the signature with the key provided by Google.
- Decryption of web-safe base64 encoded payloads.
PGP public keys provided to Google must have a subkey used for encryption. The subkey allows for independent rotation from the master key. The master key is used for identity verification. Private keys must be 2048 (or greater) bit RSA keys that expire in one year with a max lifetime of two years.
In this approach, the client will sign and encrypt the JSON body using PGP. The PGP-encoded payload will then be web-safe base64 encoded and put into the HTTP body. The client may choose to include the signatures generated by multiple private PGP keys for a single request. Further, the client may choose to encrypt using multiple public PGP keys for a single request. The public PGP keys will be exchanged at initial setup time.
For more details on this, see PGP best practices.
Transport Layer Security (TLS) authentication
The server API must be implemented as an HTTPS endpoint. The client will verify the server's identity through the trust of a Root CA. The client will have common name (CN) checking turned on. The server's CN or wildcards must match the hostname. At a minimum, the server must support TLS 1.2.
The server's certificate must be issued by a root certificate included in the Mozilla CA certification program. The use of a self signed certificate is supported, but strongly discouraged as it increases the level of maintenance necessary to keep this connection healthy.
The server's certification shouldn't be revoked by that CA; if it is revoked, Google will contact you to get a new cert immediately.
The channel will be encrypted using the session key negotiated during the TLS handshake.
For more details, see Transport Layer Encryption.