Definitions
- File Header: This is a reference to the GspFileHeader JSON object. This object will always be the first object in the settlement file.
- Settlement Header: This is a reference to the GspCardSettlementHeader which provides information about the overall settlement file. This is the second object in the file.
- Settlement Content: This refers to the set of GspCardSettlementEntry in the file which makes up the rest of the file content.
- Settlement Entry: This refers to a given GspCardSettlementEntry within the Settlement Content. It represents a single event to be settled.
GSP Card Settlement File
The file informs Google of the set of events that is to be net settled into a Google bank account.The following are the requirements for the file contents:
- The file must be in a line delimited JSON format.
- The file content must be encrypted using PGP or JWE encryption.
- The first object in the file must represent the GspFileHeader. The second object in the file must represent the GspCardSettlementHeader followed by zero or more GspCardSettlementEntry where each entry represents one event that is being settled.
- In the GspFileHeader, the
typefield must be set to “GSP_CARD_SETTLEMENT_V1” - The
entry_idwithin GspCardSettlementEntry must contain a positive integer value starting from 1 and increments with each successive entry. An example of the raw content can be found in the Non-Prettified Raw File Content.
File Naming
The naming of the file must follow the following format: GSP_CARD_SETTLEMENT_REPORT_V1-{SettlementId}-{PIAID}-{ISO 8601 Formatted FileGenerationDate(truncated to day)}-{FileGenerationTimeStamp}. The settlement ID and file creation timestamp must be the same as the Settlement Header’s settlementId and the File Header’s generationTimestamp respectively.
Here is an example of a valid name: GSP_CARD_SETTLEMENT_REPORT_V1-SettlementId1-VENDOR_1-2024-01-01-1704092400
Empty Statements
If for a given interval there are no set of events to be settled then the file should only consist of a GspFileHeader and GspCardSettlementHeader where the amount and number of items is set to 0.
File Content Regeneration
The settlement file contains output that is generated as a part of a given billing cycle. Occasionally, the file content might need to be regenerated due to incorrect calculations, logic errors, code changes, or external dependency issues.
File regeneration can be requested by Google or initiated by the payment integrator. If the regeneration is triggered by the integration then the integrator must open a line of communication beforehand.
Here are some guidelines that must be followed for the file regeneration process.
- In the GspFileHeader
- the
requestIdmust be different than the file that is being regenerated - the
generationTimestampmust be updated to the time of regeneration
- the
- In the GspCardSettlementHeader:
- You must reuse the
settlementIdof the file that is being regenerated settlementPeriodmust stay the same- the
settlementAmountmay be recalculated and updated as necessary - the
numberOfItemsmay be recalculated and updated as necessary
- You must reuse the
- File Naming
- The file generation timestamp in the filename must be updated and must match the
generationTimestampin the File Header.
- The file generation timestamp in the filename must be updated and must match the
- Settlement Content:
- It is recommended that across file regenerations, the order of the entries should be stable where possible. This allows for easy comparison across revisions thereby streamlining the operations.
Non-Prettified Raw File Content Example
NOTE: This is an accurate representation of what the raw file content looks like. For easier viewing experience and comprehension, you can reference the Prettified Raw File Content.
{"requestId":"G664529173","generationTimestamp":{"epochMillis":"1481899949606"},"type":"GSP_CARD_SETTLEMENT_V1","paymentIntegratorAccountId":"PAYMENT_INTEGRATOR"}
{"settlementId":"8pSvPpvypdti4yMTcJKUA","settlementPeriod":{"start":{"epochMillis":"1481892949606"},"end":{"epochMillis":"1481899949606"}},"settlementAmount":{"amountMicros":836000,"currencyCode":"USD"},"numberOfItems":8}
{"entryId":1,"settlementEntryType":{"captureEvent":{"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":"MCConnectivityFee"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"contract":{}},"feeType":{"authorization":{}},"feeCategory":"PFEE","feeSubCategory":"AUTHORIZATION_FEES","feeDescription":"OnlineAuthorization"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"interchange":{"interchangeCode":"MIS","interchangeQualification":"MasterCardInternationalStandard"}},"feeType":{"capture":{}},"feeCategory":"IA","feeSubCategory":"INTERCHANGE_FEES","feeDescription":"Interchange"}]}}}}
{"entryId":2,"settlementEntryType":{"refundEvent":{"asynchronousRefundRequestId":"17f76596-2ba5-4acf-806d-d6f72a70c89d","paymentIntegratorRefundId":"4378VS143UH","eventCharge":{"amountMicros":-1990000,"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":"MCConnectivityFee"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"contract":{}},"feeType":{"authorization":{}},"feeCategory":"PFEE","feeSubCategory":"AUTHORIZATION_FEES","feeDescription":"OnlineAuthorization"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"interchange":{"interchangeCode":"MIS","interchangeQualification":"MasterCardInternationalStandard"}},"feeType":{"capture":{}},"feeCategory":"IA","feeSubCategory":"INTERCHANGE_FEES","feeDescription":"Interchange"}]}}}}
{"entryId":3,"settlementEntryType":{"reverseRefundEvent":{"asynchronousRefundRequestId":"iZTHSWA6CceSU9Ze8pH1L","paymentIntegratorReverseRefundNotificationRequestId":"CfBJPCK8o5kxbSFJQiCjs","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":"MCConnectivityFee"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"contract":{}},"feeType":{"authorization":{}},"feeCategory":"PFEE","feeSubCategory":"AUTHORIZATION_FEES","feeDescription":"OnlineAuthorization"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"interchange":{"interchangeCode":"MIS","interchangeQualification":"MasterCardInternationalStandard"}},"feeType":{"capture":{}},"feeCategory":"IA","feeSubCategory":"INTERCHANGE_FEES","feeDescription":"Interchange"}]}}}}
{"entryId":4,"settlementEntryType":{"chargebackEvent":{"captureRequestId":"Z7V5TwP7CD1bJkTSaNSk3","paymentIntegratorChargebackNotificationRequestId":"Zc32x9qy354XBGMZQExrN","eventCharge":{"amountMicros":-1990000,"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":"MCConnectivityFee"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"contract":{}},"feeType":{"authorization":{}},"feeCategory":"PFEE","feeSubCategory":"AUTHORIZATION_FEES","feeDescription":"OnlineAuthorization"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"interchange":{"interchangeCode":"MIS","interchangeQualification":"MasterCardInternationalStandard"}},"feeType":{"capture":{}},"feeCategory":"IA","feeSubCategory":"INTERCHANGE_FEES","feeDescription":"Interchange"}]}}}}
{"entryId":5,"settlementEntryType":{"reverseChargebackEvent":{"captureRequestId":"J71QgkS2cMB8kEv7xAg13","paymentIntegratorReverseChargebackNotificationRequestId":"PmWXFeSGZC3QSAuTew3Yf","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":"MCConnectivityFee"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"contract":{}},"feeType":{"authorization":{}},"feeCategory":"PFEE","feeSubCategory":"AUTHORIZATION_FEES","feeDescription":"OnlineAuthorization"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"interchange":{"interchangeCode":"MIS","interchangeQualification":"MasterCardInternationalStandard"}},"feeType":{"capture":{}},"feeCategory":"IA","feeSubCategory":"INTERCHANGE_FEES","feeDescription":"Interchange"}]}}}}
{"entryId":6,"settlementEntryType":{"fundsReservationEvent":{"fundsReservationRequestId":"bNbFvwQPwukhznvu1b5s3","eventFee":{"amountMicros":-60000,"currencyCode":"USD"},"eventFeeBreakdown":{"feeDetails":[{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"scheme":{}},"feeType":{"authorization":{}},"feeCategory":"IA","feeSubCategory":"ASSESSMENT_FEES","feeDescription":"MCConnectivityFee"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"contract":{}},"feeType":{"authorization":{}},"feeCategory":"PFEE","feeSubCategory":"AUTHORIZATION_FEES","feeDescription":"OnlineAuthorization"},{"unitFee":{"amountMicros":-20000,"currencyCode":"USD"},"feeAssessmentSource":{"interchange":{"interchangeCode":"MIS","interchangeQualification":"MasterCardInternationalStandard"}},"feeType":{"capture":{}},"feeCategory":"IA","feeSubCategory":"INTERCHANGE_FEES","feeDescription":"Interchange"}]}}}}
{"entryId":7,"settlementEntryType":{"aggregateAdjustment":{"adjustmentAmount":{"amountMicros":-2000000,"currencyCode":"USD"},"adjustmentType":{"aggregatedSchemeFees":{}}}}}
{"entryId":8,"settlementEntryType":{"miscellaneousAdjustment":{"adjustmentDescription":"Reasonfortheadjustment.","adjustmentAmount":{"amountMicros":-200000,"currencyCode":"USD"}}}}
Prettified Raw File Content Example
NOTE: The content is prettified for easier viewing. See the Non-Prettified Raw File content as an accurate representation of what the file should look like.
{
"requestId": "G664529173",
"generationTimestamp": {
"epochMillis": "1481899949606"
},
"type": "GSP_CARD_SETTLEMENT_V1",
"paymentIntegratorAccountId": "PAYMENT_INTEGRATOR"
}
{
"settlementId": "8pSvPpvypdti4yMTcJKUA",
"settlementPeriod": {
"start": {
"epochMillis": "1481892949606"
},
"end": {
"epochMillis": "1481899949606"
}
},
"settlementAmount": {
"amountMicros": 836000,
"currencyCode": "USD"
},
"numberOfItems": 8
}
{
"entryId": 1,
"settlementEntryType": {
"captureEvent": {
"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"
}
]
}
}
}
}
{
"entryId": 2,
"settlementEntryType": {
"refundEvent": {
"asynchronousRefundRequestId": "17f76596-2ba5-4acf-806d-d6f72a70c89d",
"paymentIntegratorRefundId": "4378VS143UH",
"eventCharge": {
"amountMicros": -1990000,
"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"
}
]
}
}
}
}
{
"entryId": 3,
"settlementEntryType": {
"reverseRefundEvent": {
"asynchronousRefundRequestId": "iZTHSWA6CceSU9Ze8pH1L",
"paymentIntegratorReverseRefundNotificationRequestId": "CfBJPCK8o5kxbSFJQiCjs",
"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"
}
]
}
}
}
}
{
"entryId": 4,
"settlementEntryType": {
"chargebackEvent": {
"captureRequestId": "Z7V5TwP7CD1bJkTSaNSk3",
"paymentIntegratorChargebackNotificationRequestId": "Zc32x9qy354XBGMZQExrN",
"eventCharge": {
"amountMicros": -1990000,
"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"
}
]
}
}
}
}
{
"entryId": 5,
"settlementEntryType": {
"reverseChargebackEvent": {
"captureRequestId": "J71QgkS2cMB8kEv7xAg13",
"paymentIntegratorReverseChargebackNotificationRequestId": "PmWXFeSGZC3QSAuTew3Yf",
"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"
}
]
}
}
}
}
{
"entryId": 6,
"settlementEntryType": {
"fundsReservationEvent": {
"fundsReservationRequestId": "bNbFvwQPwukhznvu1b5s3",
"eventFee": {
"amountMicros": -60000,
"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"
}
]
}
}
}
}
{
"entryId": 7,
"settlementEntryType": {
"aggregateAdjustment": {
"adjustmentAmount": {
"amountMicros": -2000000,
"currencyCode": "USD"
},
"adjustmentType": {
"aggregatedSchemeFees": {}
}
}
}
}
{
"entryId": 8,
"settlementEntryType": {
"miscellaneousAdjustment": {
"adjustmentDescription": "Reason for the adjustment.",
"adjustmentAmount": {
"amountMicros": -200000,
"currencyCode": "USD"
}
}
}
}