Overview

Overview

The Card FOP (Form of Payment) API supports payments that are made using standard cards. These can be credit and debit cards. There is both a single- and dual-message flow provided for payments.

Important concepts

Symbols & Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in these documents are to be interpreted as described in RFC 2119.

Timestamps

All timestamps are represented as milliseconds since the Unix epoch in UTC.

For example:

• August 14, 2010 16:30:00.00 AM GMT = 1281803400000
• November 6, 2007 9:37:00 PM MST = 1194410220000

Amounts

Monetary values in this API are represented using a format called "micros", a standard at Google. Micros are an integer based, fixed precision format. To represent a monetary value in micros, multiply the standard currency value by 1,000,000.

For example:

• USD$1.23 = 1230000 micro USD
• USD$0.01 = 10000 micro USD

Idempotency

All method calls within this API must have idempotent behavior. Simply put, integrators should not attempt to reprocess any request already successfully processed; the response for the successful processing should be reported instead. All methods have a common RequestHeader which contains a requestId. This requestId is the idempotency key for all calls.

For any non terminal answer (a non HTTP 200), it must not be idempotently processed. So a request that previously got a 400, when called a second time must not idempotently return 400, it must be re-evalutated. At re-evaluation, it could return a 400 or be processed successfully.

For more information on idempotency see this detailed guide.

Funds transfer flow

The funds transfer flow is a single message flow in which funds are directly captured. The flow is composed of a single method that is implemented by the Payment Integrator named Capture. This method synchronously checks for available funds and captures the funds if successful.

The Payment Integrator implements

• capture

Google implements

• setAcquirerReferenceNumberForCaptureNotification

For more information on funds transfer see this detailed guide.

Refund flow

The refund flow is used to return funds that were previously captured through the funds transfer flow.

The Payment Integrator implements

• asynchronousRefund

Google implements

• refundResultNotification
• reverseRefundNotification
• setAcquirerReferenceNumberForRefundNotification

For more information on refunds see this detailed guide.

Dispute flow

The dispute flow. is used to inform Google of disputes and chargebacks where the customer is requesting to be reimbursed. Not every call implies money movement, but this flow can be used to return funds to a customer, or to reverse that and return them back to Google. This flow can be used in addition to the fraud reporting flow but does not necessarily include fraud.

Google implements

• inquiryNotification
• chargebackNotification
• chargebackReversedNotification

For more information on disputes see this detailed guide.

Fraud reporting flow

The fraud reporting flow is for informing Google of potential fraud. This information does not imply any money movement and is simply used to inform Google's Risk Engine of the event so that overall fraud can be reduced. This can be accompanied by a dispute or chargeback through the dispute flow.

Google implements

• fraudNotification

For more information on fraud reporting see this detailed guide.