# API basics

## API call flow

### Success flow

![Success flow](https://developers.google.com/static/pay/india/api/banks/loans/images/success-flow.png)

### KYC flow

![KYC flow](https://developers.google.com/static/pay/india/api/banks/loans/images/kyc-flow.png)

### eMandate flow

![eMandate flow](https://developers.google.com/static/pay/india/api/banks/loans/images/emandate-flow.png)

### Application state vs APIs

![Application state vs APIs](https://developers.google.com/static/pay/india/api/banks/loans/images/app-state.png)

## 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.

> [!IMPORTANT]
> **Important:** The server must verify that every request is signed by Google's private PGP key.

For more details on this, see [PGP best practices](https://developers.google.com/standard-payments/guides/connectivity/security/application-layer#pgp_encryption).

### 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](https://www.mozilla.org/about/governance/policies/security-group/certs/policy/).
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](https://developers.google.com/standard-payments/guides/connectivity/security/transport-layer).