HTTP API Standards

The API follows a set of HTTP API standards and supports Idempotency to facilitate a more robust integration. PGP encrypted payloads use the content type application/octet-stream; charset=utf-8 and are sent using base64url encoding, as defined in rfc4648 §5.

HTTP paths

Google hosted URLs

The documentation for each Google-hosted method provides a base URL, which includes the method name and major version number. The complete URL is created by adding the caller's Payment Integrator Account ID to the end. For example, the documentation for the Google-hosted echo method specifies the URL:

https://billpaynotification.googleapis.com/secure-serving/gsp/v1/echo

If the caller's Payment Integrator Account ID is INTEGRATOR_1, they would add that to the end of the URL to form:

https://billpaynotification.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

Partner hosted URLs

The documentation for each partner hosted API method provides a base URL, which includes the method name and major version number. You should not include the Payment Integrator Account ID (PIAID) in the URLs you host.

HTTP response codes

The server application must return 200 for all requests it accepts. This includes both successful and declined requests.

If a request cannot be processed, this represents an error between Google and the payment integrator. In error situations an HTTP 200 must not be returned. You must use an error code from the table below. In order to provide more detailed diagnostic information the HTTP body can be an ErrorResponse, however it is acceptable to have an empty HTTP body as well. Error responses must not be cached or returned idempotently, as a change in system state may result in subsequent retries succeeding.

HTTP Errors And Reasons
400 BAD REQUEST / FAILED PRECONDITION

Client specified an invalid argument. Note that this should not be used for situations where an appropriate application error is available. For example, incorrect currencies should return ACCOUNT_DOES_NOT_SUPPORT_CURRENCY, not 400.

This can also be returned if the operation was rejected because the system is not in a state required for the operation's execution.

Use this if retries of the request cannot succeed until the system state has been explicitly fixed. For example, if a refund request fails because it references a capture that does not exist, retrying will not succeed until the capture exists in the integrators system.

401 UNAUTHORIZED

The request does not have valid authentication credentials for the operation. For example, invalid signatures or unknown signatures should return 401.

403 FORBIDDEN / PERMISSION DENIED

The caller does not have permission to execute the specified operation.

404 NOT FOUND

Some requested entity such as payment or user was not found.

409 CONFLICT / ABORTED

The operation was aborted, typically due to a concurrency issue like sequencer-check failures, transaction aborts, etc.

412 PRECONDITION FAILED

This code should be used in situations where an idempotency key is being reused with different parameters.

429 RESOURCE EXHAUSTED / TOO MANY REQUESTS

Some system resource has exhausted.

499 CANCELLED

The operation was cancelled (typically by the caller).

500 INTERNAL ERROR

Internal errors. This means some invariants expected by underlying system has been broken.

501 UNIMPLEMENTED

Operation is not implemented, supported or enabled in this service.

503 UNAVAILABLE

The service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying.

504 GATEWAY TIMEOUT / DEADLINE EXCEEDED

Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.

Error results must never be cached or idempotently returned.