- HTTP request
- Request body
- Response body
- Interval
- CaptureEvent
- EventPresentmentDetails
- EventFeeBreakdown
- FeeDetail
- FeeAssessmentSource
- InterchangeFee
- FeeType
- RefundEvent
- ReverseRefundEvent
- ChargebackEvent
- ReverseChargebackEvent
- FundsReservationEvent
- AggregateAdjustment
- AdjustmentType
- AggregatedFees
- MiscellaneousAdjustment
- SettlementNotificationResponse
- Result
Informs Google that a set of events will be net settled in bulk into a Google bank account.
If the endpoint encounters an error while processing the request, the response from this endpoint will be of type ErrorResponse
.
Responses to this query may be empty if this method does not return an HTTP 200. The response body is empty in situations where an ErrorResponse
with a clear description could be used to help an attacker understand the payment integrator account identifier of other integrators. In these situations, where either the signing key doesn't match, the payment integrator identifier was not found, or the encryption key was unknown, this method will return an HTTP 404 with an empty body. If the request signature could be verified, additional information regarding the error will be returned in the response body.
An example request looks like:
{
"requestHeader": {
"protocolVersion": {
"major": 1
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp":{
"epochMillis": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD"
},
"generatedTimestamp": {
"epochMillis": "1481899949606"
},
"settlementPeriod": {
"start": {
"epochMillis": "1481892949606"
},
"end": {
"epochMillis": "1481899949606"
}
},
"settlementAmount": {
"amountMicros": "836000",
"currencyCode": "USD"
},
"settlementId": "STL_423JRE41",
"notificationOffset": 0,
"notificationTotal": 2,
"captureEvents": [
{
"captureRequestId": "076c1924-e8b3-4168-b456-363f72f5d7f1",
"paymentIntegratorCaptureId": "12439VSDERA4",
"eventCharge": {
"amountMicros": "2000000",
"currencyCode": "USD"
},
"eventFee": {
"amountMicros": "-60000",
"currencyCode": "USD"
},
"eventVat": {
"amountMicros": "-20000",
"currencyCode": "USD"
},
"eventFeeBreakdown": {
"feeDetails": [
{
"unitFee": {
"amountMicros": "-20000",
"currencyCode": "USD"
},
"feeAssessmentSource": {
"scheme": {}
},
"feeType": {
"authorization": {}
},
"feeCategory": "IA",
"feeSubCategory": "ASSESSMENT_FEES",
"feeDescription": "MC Connectivity Fee"
},
{
"unitFee": {
"amountMicros": "-20000",
"currencyCode": "USD"
},
"feeAssessmentSource": {
"contract": {}
},
"feeType": {
"authorization": {}
},
"feeCategory": "PFEE",
"feeSubCategory": "AUTHORIZATION_FEES",
"feeDescription": "Online Authorization"
},
{
"unitFee": {
"amountMicros": "-20000",
"currencyCode": "USD"
},
"feeAssessmentSource": {
"interchange": {
"interchangeCode": "MIS",
"interchangeQualification": "MasterCard International Standard"
}
},
"feeType": {
"capture": {}
},
"feeCategory": "IA",
"feeSubCategory": "INTERCHANGE_FEES",
"feeDescription": "Interchange"
}
]
}
},
{
"captureRequestId": "5cbbb5d7-523d-443e-86ef-8a480e5547c1",
"paymentIntegratorCaptureId": "H4ARKL3431",
"eventCharge": {
"amountMicros": "2990000",
"currencyCode": "USD"
},
"eventFee": {
"amountMicros": "-63000",
"currencyCode": "USD"
},
"eventVat": {
"amountMicros": "-21000",
"currencyCode": "USD"
},
"eventFeeBreakdown": {
"feeDetails": [
{
"unitFee": {
"amountMicros": "-21000",
"currencyCode": "USD"
},
"feeAssessmentSource": {
"contract": {}
},
"feeType": {
"capture": {}
},
"feeCategory": "PFEE",
"feeSubCategory": "DEPOSIT_FEES",
"feeDescription": "Settled Dep. Fee"
},
{
"unitFee": {
"amountMicros": "-21000",
"currencyCode": "USD"
},
"feeAssessmentSource": {
"interchange": {
"interchangeCode": "MM1P",
"interchangeQualification": "MC AVS Card Not Present Fee"
}
},
"feeType": {
"authorization": {}
},
"feeCategory": "IA",
"feeSubCategory": "INTERCHANGE_FEES",
"feeDescription": "Interchange"
},
{
"unitFee": {
"amountMicros": "-21000",
"currencyCode": "USD"
},
"feeAssessmentSource": {
"interchange": {
"interchangeCode": "MM1P",
"interchangeQualification": "MC Reporting&Infrastructure"
}
},
"feeType": {
"capture": {}
},
"feeCategory": "IA",
"feeSubCategory": "INTERCHANGE_FEES",
"feeDescription": "Interchange"
}
]
}
}
],
"refundEvents": [
{
"asynchronousRefundRequestId": "17f76596-2ba5-4acf-806d-d6f72a70c89d",
"paymentIntegratorRefundId": "4378VS143UH",
"eventCharge": {
"amountMicros": "-1990000",
"currencyCode": "USD"
},
"eventFee": {
"amountMicros": "0",
"currencyCode": "USD"
},
"eventVat": {
"amountMicros": "0",
"currencyCode": "USD"
}
}
],
"reverseRefundEvents": [],
"chargebackEvents": [],
"reverseChargebackEvents": [],
"aggregateAdjustments": [
{
"adjustmentAmount": {
"amountMicros": "-2000000",
"currencyCode": "USD"
},
"adjustmentType": {
"chargebackThresholdFine": {}
}
}
]
}
An example success response looks like:
{
"responseHeader": {
"responseTimestamp": {
"epochMillis": "1481899950236"
}
},
"result": {
"accepted": {}
}
}
HTTP request
POST https://vgw.googleapis.com/gsp/v1/settlementNotification/:PIAID
Request body
The request body contains data with the following structure:
JSON representation |
---|
{ "requestHeader": { object (RequestHeader) }, "generatedTimestamp": { object (Timestamp) }, "settlementPeriod": { object ( |
Fields | |
---|---|
request |
REQUIRED: Common header for all requests. |
generated |
REQUIRED: Timestamp of when this report was generated. |
settlement |
REQUIRED: The period this settlement report covers. |
settlement |
REQUIRED: This should match the sum of all the |
settlement |
REQUIRED: This should be a unique ID that identifies the settlement report. All |
notification |
REQUIRED: This is the offset of this |
notification |
REQUIRED: The total number of |
capture |
REQUIRED: Set of capture events. |
refund |
REQUIRED: Set of refund events. |
reverse |
REQUIRED: Set of reverse refund events. |
chargeback |
REQUIRED: Set of chargeback events. |
reverse |
REQUIRED: Set of reverse chargeback events. |
funds |
REQUIRED: Set of funds reservation events. |
aggregate |
REQUIRED: Adjustments that don't apply to an individual transaction. |
Response body
This method supports multiple return types. For additional information about what 4XX or 5XX HTTP status code to return with an ErrorResponse
, consult the ErrorResponse
object and HTTP status codes documentation.
Possible response messages | |
---|---|
HTTP 200 Status |
|
HTTP 4XX / 5XX Status |
|
Interval
A length of time with a chronological beginning and end.
JSON representation |
---|
{ "start": { object (Timestamp) }, "end": { object (Timestamp) } } |
Fields | |
---|---|
start |
REQUIRED: The start of this interval, which is inclusive. |
end |
REQUIRED: The end of this interval, which is exclusive. |
CaptureEvent
This represents a payment where a customer is charged. It is associated with a capture
, asynchronousCaptureFundsReservation
or beginRedirect
event.
JSON representation |
---|
{ "captureRequestId": string, "paymentIntegratorCaptureId": string, "eventCharge": { object (Amount) }, "eventPresentmentDetails": { object ( |
Fields | |
---|---|
capture |
REQUIRED: |
payment |
REQUIRED: An ID that is generated by the payment integrator that can be used to refer to this capture event. |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. |
event |
OPTIONAL: If the settlement currency is different than the purchase currency then this field should be used to specify details about the event in the original purchase currency and the conversion to the settlement amount. |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. If the fee is broken down into several parts, this value is the sum of them and the amount settled. A breakdown of the fee can be specified in the |
event |
OPTIONAL: This is a breakdown of the |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. This is the value-added-tax (VAT) for the |
EventPresentmentDetails
This represents a presentment currency and a conversion rate in case the settlement and the purchase currencies are different.
JSON representation |
---|
{ "presentmentAmount": { object (Amount) }, "nanoExchangeRate": string } |
Fields | |
---|---|
presentment |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. The presentment amount of the purchase in the currency that was used for the purchase. This should only be specified if the purchase currency is different than the settlement currency. |
nano |
REQUIRED: The exchange rate used in converting the presentment amount to the settlement (invoice) amount. This value is in nano basis points (1 basis point = .0001 = .01%). That is, to get the exchange rate, divide this field by 10^13. Example:
|
EventFeeBreakdown
This represents a breakdown of the eventFee
that can be used for reporting purposes to better understand the fee makeup.
JSON representation |
---|
{
"feeDetails": [
{
object ( |
Fields | |
---|---|
fee |
|
FeeDetail
This represents details of a fee event.
JSON representation |
---|
{ "unitFee": { object (Amount) }, "feeAssessmentSource": { object ( |
Fields | |
---|---|
unit |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. The amount of the fee being described. This can be smaller than the minimum billible unit. The sum of all the |
fee |
REQUIRED: The source that is assessing the fee. |
fee |
REQUIRED: This is the type of the fee event. It might match the event type, but it doesn't have to. For example, an authorization fee might be assessed with a |
fee |
REQUIRED: The category of the fee. e.g. Discount, Fee, etc. |
fee |
REQUIRED: The category of the fee. e.g. Authorization, assessment, deposit, etc. |
fee |
REQUIRED: A description of the fee. This field is not parsed by the system and is only for human consumption to better understand the fee. |
FeeAssessmentSource
The source that assessed the fee.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
scheme |
The fee is assessed by the scheme or network. |
interchange |
The fee is assessed as part of the interchange fee. |
contract |
The fee is specified in the contract between Google and the payment integrator. |
InterchangeFee
Detailed information about an interchange fee.
JSON representation |
---|
{ "interchangeCode": string, "interchangeQualification": string } |
Fields | |
---|---|
interchange |
REQUIRED: The interchange fee code. |
interchange |
REQUIRED: The qualification of the interchange fee. |
FeeType
The type of fee.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
authorization |
The fee is assessed as part of an authorization. |
capture |
The fee is assessed as part of a capture. |
refund |
The fee is assessed as part of a refund. |
chargeback |
The fee is assessed as part of a chargeback. |
reverse |
The fee is assessed as part of a reverse chargeback. |
reverse |
The fee is assessed as part of a reverse refund. |
fx |
The fee is assessed as part of an exchange rate markup. |
auth |
Fee associated with a reversal of an authorization event. |
partial |
Fee associated with a partial refund event. |
RefundEvent
This represents a refund where money is being returned to a customer. It will be associated with a refund
event.
JSON representation |
---|
{ "asynchronousRefundRequestId": string, "paymentIntegratorRefundId": string, "eventCharge": { object (Amount) }, "eventPresentmentDetails": { object ( |
Fields | |
---|---|
asynchronous |
REQUIRED: |
payment |
REQUIRED: An ID that is generated by the payment integrator that can be used to refer to this refund event. |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. |
event |
OPTIONAL: If the settlement currency is different than the purchase currency then this field should be used to specify details about the event in the original purchase currency and the conversion to the settlement amount. |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. If the fee is broken down into several parts, this value is the sum of them and the amount settled. A breakdown of the fee can be specified in the For example, if an agreement says that Google will pay 1% of the |
event |
OPTIONAL: This is a breakdown of the |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. This is the value-added-tax (VAT) for the |
ReverseRefundEvent
This represents a reverse refund. It is associated with a reverseRefundNotification
and typically is used when a refund was performed but the issuing bank was unable to return funds to the customer, so they are being returned to Google.
JSON representation |
---|
{ "asynchronousRefundRequestId": string, "paymentIntegratorReverseRefundNotificationRequestId": string, "eventCharge": { object (Amount) }, "eventPresentmentDetails": { object ( |
Fields | |
---|---|
asynchronous |
REQUIRED: |
payment |
REQUIRED: This is the |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. |
event |
OPTIONAL: If the settlement currency is different than the purchase currency then this field should be used to specify details about the event in the original purchase currency and the conversion to the settlement amount. |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. If the fee is broken down into several parts, this value is the sum of them and the amount settled. A breakdown of the fee can be specified in the For example, if an agreement says that Google will pay 1% of the |
event |
OPTIONAL: This is a breakdown of the |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. This is the value-added-tax (VAT) for the |
ChargebackEvent
This represents a chargeback. It is associated with a chargebackNotification
and is used when a customer disputes a payment made in a capture
or asynchronousCaptureFundsReservation
. This is used to return funds to the customer.
JSON representation |
---|
{ "captureRequestId": string, "paymentIntegratorChargebackNotificationRequestId": string, "eventCharge": { object (Amount) }, "eventPresentmentDetails": { object ( |
Fields | |
---|---|
capture |
REQUIRED: |
payment |
REQUIRED: This is the |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. |
event |
OPTIONAL: If the settlement currency is different than the purchase currency then this field should be used to specify details about the event in the original purchase currency and the conversion to the settlement amount. |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. If the fee is broken down into several parts, this value is the sum of them and the amount settled. A breakdown of the fee can be specified in the For example, if an agreement says that Google will pay 1% of the |
event |
OPTIONAL: This is a breakdown of the |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. This is the value-added-tax (VAT) for the |
ReverseChargebackEvent
This represents a reverse chargeback. It is associated with a reverseChargebackNotification
and is used when Google successfully disputes a chargebackNotification
. The funds are being returned to Google.
JSON representation |
---|
{ "captureRequestId": string, "paymentIntegratorReverseChargebackNotificationRequestId": string, "eventCharge": { object (Amount) }, "eventPresentmentDetails": { object ( |
Fields | |
---|---|
capture |
REQUIRED: |
payment |
REQUIRED: This is the |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. |
event |
OPTIONAL: If the settlement currency is different than the purchase currency then this field should be used to specify details about the event in the original purchase currency and the conversion to the settlement amount. |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. If the fee is broken down into several parts, this value is the sum of them and the amount settled. A breakdown of the fee can be specified in the For example, if an agreement says that Google will pay 1% of the |
event |
OPTIONAL: This is a breakdown of the |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. This is the value-added-tax (VAT) for the |
FundsReservationEvent
This represents fees associated with a funds reservation. It is associated with a reserveFunds
.
JSON representation |
---|
{ "fundsReservationRequestId": string, "eventFee": { object (Amount) }, "eventFeeBreakdown": { object ( |
Fields | |
---|---|
funds |
REQUIRED: |
event |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. If the fee is broken down into several parts, this value is the sum of them and the amount settled. A breakdown of the fee can be specified in the |
event |
OPTIONAL: This is a breakdown of the |
event |
REQUIRED: Specify details about the funds reservation currency, amount and the conversion rate to the settlement currency. |
AggregateAdjustment
This represents settlement of amounts that don't apply to a specific transaction and instead occur in aggregate.
JSON representation |
---|
{
"adjustmentAmount": {
object (Amount)
},
"adjustmentType": {
object ( |
Fields | |
---|---|
adjustment |
REQUIRED: If this amount is negative then it represents monetary value moving from Google to the payment integrator. If this is positive it is money from the payment integrator due to Google. The amount of the adjustment that will be factored into the |
adjustment |
REQUIRED: This provides more information about the adjustment. |
AdjustmentType
This provides more information about the adjustment type.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
aggregated |
Credit card authorization fees aggregated over a period of time. This should only be used if those fees aren't provided at the transaction level via the |
aggregated |
Chargeback fees aggregated over a period of time. This should only be used if those fees can't be provided at the transaction level via the |
aggregated |
Aggregated integrity fees over a period of time. Integrity fees are imposed by a card network for transactions that were not 3DS-authenticated. This should only be used if those fees aren't provided at the transaction level via the |
aggregated |
Aggregate change in authorization fees due to updated rates or some other factor that was unknown when the authorization fees were originally set in the |
aggregated |
Aggregate change in chargeback fees due to updated rates or some other factor that was unknown when the chargeback fees were originally set in the |
aggregated |
Aggregate change in integrity fees due to updated rates or some other factor that was unknown when the integrity fees were originally set in the |
chargeback |
Card networks (eg VISA, MC) have Dispute Monitoring Programs. A fine can be imposed by a card network for breaking a certain chargeback threshold in terms of a number of chargebacks per a period of time. |
miscellaneous |
Miscellaneous type is used only when other types are not suitable. It is recommended to use miscellaneous type only occasionally and only in exceptional situations. Google will monitor for usage of this AdjustmentType and consider it a bug if a payment integrator uses this option systematically. If the existing adjustment types are not suitable, Google is willing to discuss adding a more targeted type. |
event |
Used to account for adjustment in the rounding of event fees. If the event fees do not sum to a round number of billable units, then this value should be used to account for the rounding to billable units. It can be represented as sub-billable units. e.g. if the event fees sum to $10.053 USD and $10.06 would be the settlement amount than this can capture the missing $0.007 USD so it is accounted for. This amount can be larger than a single billable unit if the rounding is occurring in multiple places. |
aggregated |
Aggregate fees charged by the networks. |
aggregated |
Aggregate Goods and Service Tax. |
aggregated |
Aggregate fees variance charged by the networks due to updated rates or some other factor that was unknown when the scheme fees were originally set in the 'eventFee' field with the transactions. |
AggregatedFees
This represents an aggregated transaction-level fees.
JSON representation |
---|
{ "numberOfEvents": string } |
Fields | |
---|---|
number |
Number of events (eg payments) that fees are aggregated across. |
MiscellaneousAdjustment
This represents an unforeseen adjustment type that a payment integrator submits only in an exceptional circumstances.
JSON representation |
---|
{ "adjustmentDescription": string } |
Fields | |
---|---|
adjustment |
REQUIRED: Adjustment description should clearly explain a nature and exceptional circumstances of the adjustment. |
SettlementNotificationResponse
Response object for the settlementNotification
method.
JSON representation |
---|
{
"responseHeader": {
object (ResponseHeader)
},
"result": {
object ( |
Fields | |
---|---|
response |
REQUIRED: Common header for all responses. |
result |
REQUIRED: Contains the result of the request. |
Result
Details corresponding to the result.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
accepted |
The |