{ "swagger": "2.0", "info": { "title": "Google Standard Payments Payment Integrator Hosted ValueOnDevice FOP API", "description": "This includes services hosted by Payment Integrators for ValueOnDevice FOPs.", "version": "v1" }, "host": "www.integratorhost.example.com", "basePath": "/integrator-base-path", "schemes": ["https"], "paths": { "/value-on-device-fop-v1/echo": { "post": { "tags": ["payment_integrator_value_on_device_fop_api"], "operationId": "Echo", "description": "Echos back the `clientMessage` that is passed in. The purpose of this method is to test basic connectivity between the payment integrator and Google. This method may be called by Google multiple times per minute with valid or invalid parameters in order to test that security constraints are being held properly. Google also calls this method ad-hoc at the integrator's direction as well as at Google's direction. Google will never call this faster than once every 10s, and never more than 30 times in a 15 minute window. Examples of security constraint tests are (but not limited to): - Test to ensure payment integrator's endpoint doesn't negotiate to weak cipher suites. - Test to ensure payment integrator's endpoint doesn't negotiate to anything but TLS 1.2 - Test to ensure payment integrator's endpoint doesn't support HTTP. - Test to ensure payment integrator's endpoint mandates at least one known PGP signing key. - Test to ensure payment integrator's endpoint supports multiple PGP key signatures, both known and unknown, both expired and active. - Test to ensure payment integrator only support strict JSON parsing. If the endpoint encounters an error while processing the request, the response body from this endpoint should be of type `ErrorResponse`. An example request looks like: { \"requestHeader\": { \"protocolVersion\": { \"major\": 1, \"minor\": 0, \"revision\": 0 }, \"requestId\": \"ZWNobyB0cmFuc2FjdGlvbg\", \"requestTimestamp\": \"1481899949606\" }, \"clientMessage\": \"client message\" } An example response looks like: { \"responseHeader\": { \"responseTimestamp\": \"1481900013178\" }, \"clientMessage\": \"client message\", \"serverMessage\": \"server message\" } ", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/EchoRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/EchoResponse" } } } } }, "/value-on-device-fop-v1/remittanceStatementNotification": { "post": { "tags": ["payment_integrator_value_on_device_fop_api"], "operationId": "RemittanceStatementNotification", "description": "Notifies the integrator of a new remittance statement. Statement notifications occur everytime a new statement is raised that represents money that Google will pay the integrator or the money that the integrator owes Google. If the integrator returns a success, then it acknowledges receipt of the statement. The `requestId` is also the statement Id (used elsewhere). The `requestId` within the header is the idempotency key and uniquely identifies this statement. If the endpoint encounters an error while processing the request, the response body from this endpoint should be of type `ErrorResponse`. An example request looks like: { \"requestHeader\": { \"protocolVersion\": { \"major\": 1, \"minor\": 0, \"revision\": 0 }, \"requestId\": \"0123434-statement-abc\", \"requestTimestamp\": \"1502632800000\" }, \"paymentIntegratorAccountId\": \"InvisiCashUSA_USD\", \"remittanceStatementSummary\": { \"statementDate\": \"1502607600000\", \"billingPeriod\": { \"startDate\": \"1502434800000\", \"endDate\": \"1502521199000\" }, \"dateDue\": \"1503212400000\", \"currencyCode\": \"INR\", \"totalDueByIntegrator\": \"1076000000\", \"totalPresentmentAmounts\": [ { \"amountMicros\": \"1076000000\", \"currencyCode\": \"INR\" } ], \"remittanceInstructions\": { \"memoLineId\": \"stmt-1AB-pp0-invisi\" } } } An example response looks like: { \"responseHeader\": { \"responseTimestamp\": \"1502632802000\" }, \"paymentIntegratorStatementId\": \"334a\", \"result\": \"ACCEPTED\" } ", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/RemittanceStatementNotificationRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/RemittanceStatementNotificationResponse" } } } } }, "/value-on-device-fop-v1/generateDeviceCaptureToken": { "post": { "tags": ["payment_integrator_value_on_device_fop_api"], "operationId": "GenerateDeviceCaptureToken", "description": "Requests a token from the integrator that can be executed on the user's device in order to debit the device's stored value. The combination of `requestId` within the header and `paymentIntegratorAccountId` is the idempotency key and uniquely identifies this transaction. All mutations on this transaction (refunds) populate the `requestId` value in the `captureRequestId` field. If the endpoint encounters an error while processing the request, the response body from this endpoint should be of type `ErrorResponse`. An example request looks like: { \"requestHeader\": { \"protocolVersion\": { \"major\": 1, \"minor\": 1, \"revision\": 0 }, \"requestId\": \"bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ\", \"requestTimestamp\": \"1502220196077\" }, \"paymentIntegratorAccountId\": \"InvisiCashUSA_USD\", \"transactionDescription\": \"Google - Music\", \"currencyCode\": \"JPY\", \"amount\": \"545000000\", \"deviceIdentifier\": \"FC199014344145\", \"instanceIdentifier\": \"ID15626388286838485\", \"sessionIdentifier\": \"5226453\", \"balance\": \"16000000\" } An example response looks like: { \"responseHeader\": { \"responseTimestamp\": \"1481900013178\" }, \"result\": { \"generateDeviceCaptureTokenResultCode\": \"SUCCESS\" }, \"paymentIntegratorTransactionId\": \"aW50ZWdyYXRvciB0cmFuc2FjdGlvbiBpZA\", \"deviceCaptureToken\": \"WW91IHN1cmUgYXJlIGN1cmlvdXMsIGFyZW4ndCB5b3U\/\" } ", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/GenerateDeviceCaptureTokenRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/GenerateDeviceCaptureTokenResponse" } } } } }, "/value-on-device-fop-v1/getDeviceCaptureResult": { "post": { "tags": ["payment_integrator_value_on_device_fop_api"], "operationId": "GetDeviceCaptureResult", "description": "Requests the result of the execution of a previously generated device capture token. If the endpoint encounters an error while processing the request, the response body from this endpoint should be of type `ErrorResponse`. An example request looks like: { \"requestHeader\": { \"protocolVersion\": { \"major\": 1, \"minor\": 1, \"revision\": 0 }, \"requestId\": \"bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ\", \"requestTimestamp\": \"1502220196077\" }, \"paymentIntegratorAccountId\": \"InvisiCashUSA_USD\", \"deviceCaptureRequestId\": \"WW91IHN1cFyZW4ndCB5b3U\" } An example response looks like: { \"responseHeader\": { \"responseTimestamp\": \"1481900013178\" }, \"result\": \"SUCCESS\", \"deviceCaptureResult\": { \"deviceCaptureResultCode\": \"SUCCESS\" } } ", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/GetDeviceCaptureResultRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/GetDeviceCaptureResultResponse" } } } } } }, "definitions": { "EchoRequest": { "description": "Request object for the echo method.", "type": "object", "properties": { "requestHeader": { "description": "**REQUIRED**: Common header for all requests.", "$ref": "#/definitions/RequestHeader" }, "clientMessage": { "description": "**REQUIRED**: Message to echo in the response.", "type": "string" } } }, "RequestHeader": { "description": "Header object that is defined on all requests sent to the server.", "type": "object", "properties": { "requestId": { "description": "**REQUIRED**: Unique identifier of this request. This is a string that has a max length of 100 characters, and contains only the characters \"a-z\", \"A-Z\", \"0-9\", \":\", \"-\", and \"_\".", "type": "string" }, "requestTimestamp": { "description": "**REQUIRED**: Timestamp of this request represented as milliseconds since epoch. The receiver should verify that this timestamp is \u00B1 60s of 'now'. This request timestamp is not idempotent upon retries.", "type": "string", "format": "int64" }, "userLocale": { "description": "**DEPRECATED**: A two- or three-letter ISO 639-2 Alpha 3 language code optionally followed by a hyphen and an ISO 3166-1 Alpha-2 country code, e.g.'pt', 'pt-BR', 'fil', or 'fil-PH'. Use this to help drive the `userMessage` fields in the response.", "type": "string" }, "protocolVersion": { "description": "**REQUIRED**: The version of this request.", "$ref": "#/definitions/Version" } } }, "Version": { "description": "Version object which is a structured form of the classic `a.b.c` version structure. Major versions of the same number are guaranteed to be compatible. Note that minor and revisions can change frequently and without notice. The integrator must support all requests for the same major version.", "type": "object", "properties": { "major": { "description": "**REQUIRED**: Major version. This is marked for compatibility requests with different versions are not guaranteed to be compatible.", "type": "integer", "format": "int32" }, "minor": { "description": "**REQUIRED**: Minor version. This denotes significant bug fixes.", "type": "integer", "format": "int32" }, "revision": { "description": "**REQUIRED**: Minor version. This denotes minor bug fixes.", "type": "integer", "format": "int32" } } }, "EchoResponse": { "description": "Response object for the echo method.", "type": "object", "properties": { "responseHeader": { "description": "**REQUIRED**: Common header for all responses.", "$ref": "#/definitions/ResponseHeader" }, "clientMessage": { "description": "**REQUIRED**: Message received in the request.", "type": "string" }, "serverMessage": { "description": "**OPTIONAL**: Server message, independent of the `clientMessage` being echoed.", "type": "string" } } }, "ResponseHeader": { "description": "Header object that is defined on all responses sent from the server.", "type": "object", "properties": { "responseTimestamp": { "description": "**REQUIRED**: Timestamp of this response represented as milliseconds since epoch. The receiver should verify that this timestamp is \u00B1 60s of 'now'.", "type": "string", "format": "int64" } } }, "ErrorResponse": { "description": "Error Response object for all methods.", "type": "object", "properties": { "responseHeader": { "description": "**REQUIRED**: Common header for all responses.", "$ref": "#/definitions/ResponseHeader" }, "errorResponseCode": { "description": "**OPTIONAL**: A code that captures the type of error that occurred.", "type": "string", "enum": [ "UNKNOWN_ERROR_RESPONSE_CODE", "INVALID_API_VERSION", "INVALID_PAYLOAD_SIGNATURE", "INVALID_PAYLOAD_ENCRYPTION", "REQUEST_TIMESTAMP_OUT_OF_RANGE", "INVALID_IDENTIFIER", "IDEMPOTENCY_VIOLATION", "INVALID_FIELD_VALUE", "MISSING_REQUIRED_FIELD", "PRECONDITION_VIOLATION", "USER_ACTION_IN_PROGRESS", "INVALID_DECRYPTED_REQUEST", "FORBIDDEN" ] }, "errorDescription": { "description": "**OPTIONAL**: Provide a description of this status for support reps to debug errors. Note that this is never shown to users. It can contain descriptive, non-sensitive text used for debugging. Note that some values for errorResponseCode should be accompanied by additional detail in this field. For example, `INVALID_IDENTIFIER` should be accompanied by information in this field as to which type of identifier was invalid. Warning: Do not include any tokens in this message unless they are defined as public.", "type": "string" }, "paymentIntegratorErrorIdentifier": { "description": "**OPTIONAL**: This identifier is specific to the integrator and is generated by the integrator. It is used for debugging purposes only in order to identify this call. This is the identifier that the integrator knows this call by.", "type": "string" } } }, "RemittanceStatementNotificationRequest": { "description": "Request object for the remittance statement notification method.", "type": "object", "properties": { "requestHeader": { "description": "**REQUIRED**: Common header for all requests.", "$ref": "#/definitions/RequestHeader" }, "paymentIntegratorAccountId": { "description": "**REQUIRED**: This is the payment integrator account identifier that identifies contractual constraints around this statement.", "type": "string" }, "remittanceStatementSummary": { "description": "**REQUIRED**: Summary of this remittance statement.", "$ref": "#/definitions/RemittanceStatementSummary" } } }, "RemittanceStatementSummary": { "description": "Summary object about a remittance statement.", "type": "object", "properties": { "statementDate": { "description": "**REQUIRED**: Date (in America\/Los Angeles) that this statement was created.", "type": "string", "format": "int64" }, "billingPeriod": { "description": "**REQUIRED**: The billing period this statement covers.", "$ref": "#/definitions/BillingPeriod" }, "dateDue": { "description": "**OPTIONAL**: The date that the remittance is due. This is represented as milliseconds from epoch. It is a date (and therefore will always start at the first millisecond of the day in the billing timezone). This is set as long as the `totalDueByIntegrator` is greater than 0.", "type": "string", "format": "int64" }, "currencyCode": { "description": "**REQUIRED**: ISO 4217 3-letter currency code.", "type": "string" }, "totalDueByIntegrator": { "description": "**REQUIRED**: This value is in micros in the currency of `currencyCode`. This value is always positive.", "type": "string", "format": "int64" }, "remittanceInstructions": { "description": "**REQUIRED**: Details on how to remit payment", "$ref": "#/definitions/RemittanceInstructions" }, "totalPresentmentAmounts": { "description": "**REQUIRED**: This is the total amount presented to the customer. There will be one entry for each presentment currency.", "type": "array", "items": { "$ref": "#/definitions/Amount" } } } }, "BillingPeriod": { "description": "Billing period of this statement.", "type": "object", "properties": { "startDate": { "description": "**REQUIRED**: The start date of the billing period. This is represented as milliseconds from epoch. It is a date (and therefore will always start at the first millisecond of the day in the billing timezone). This is the first millisecond of the day of the billing period, 00:00:00.000", "type": "string", "format": "int64" }, "endDate": { "description": "**REQUIRED**: The end date of the billing period. This is represented as milliseconds from epoch. This is the last millisecond of the last day of the billing period, 23:59:59.999", "type": "string", "format": "int64" } } }, "RemittanceInstructions": { "description": "Structure holding information about how to pay this remittance notification.", "type": "object", "properties": { "memoLineId": { "description": "**REQUIRED**: Identifier that is mandatory to be put on the memo line for the payment for remittance identification.", "type": "string" } } }, "Amount": { "description": "Associates an amount in micros with a currency code.", "type": "object", "properties": { "amountMicros": { "description": "**REQUIRED**: An amount in [micros]({{glossary_path}}#micros \"What are micros?\").", "type": "string", "format": "int64" }, "currencyCode": { "description": "**REQUIRED**: ISO 4217 3-letter currency code", "type": "string" } } }, "RemittanceStatementNotificationResponse": { "description": "Response object for the remittance statement notification method.", "type": "object", "properties": { "responseHeader": { "description": "**REQUIRED**: Common header for all responses.", "$ref": "#/definitions/ResponseHeader" }, "paymentIntegratorStatementId": { "description": "**REQUIRED**: Identifier the integrator knows this statement as. This is integrator generated.", "type": "string" }, "result": { "description": "**REQUIRED**: Result of this statement notification.", "type": "string", "enum": [ "UNKNOWN_RESULT", "ACCEPTED" ] } } }, "GenerateDeviceCaptureTokenRequest": { "description": "Request object for the generateDeviceCaptureToken method.", "type": "object", "properties": { "requestHeader": { "description": "**REQUIRED**: Common header for all requests.", "$ref": "#/definitions/RequestHeader" }, "paymentIntegratorAccountId": { "description": "**REQUIRED**: This is the payment integrator account identifier that identifies contractual constraints around this transaction.", "type": "string" }, "currencyCode": { "description": "**REQUIRED**: ISO 4217 3-letter currency code", "type": "string" }, "amount": { "description": "**REQUIRED**: The amount of the purchase, in [micros]({{glossary_path}}#micros \"What are micros?\") of the currency unit.", "type": "string", "format": "int64" }, "transactionDescription": { "description": "**REQUIRED**: This is the description of the transaction that can be put on the customer's statement. Localized to the userLocale found in the `requestHeader`. This format can be changed without notice and must never be parsed.", "type": "string" }, "deviceIdentifier": { "description": "**REQUIRED**: Identifies the device this token should be built for. This is a hardware identifier.", "type": "string" }, "instanceIdentifier": { "description": "**REQUIRED**: Identifies the eMoney card instance this token should be built for.", "type": "string" }, "sessionIdentifier": { "description": "**OPTIONAL**: An identifier for this particular transaction or session that we are executing on the Secure Element.", "type": "string" }, "balance": { "description": "**OPTIONAL**: The current balance on the Secure Element, in [micros]({{glossary_path}}#micros \"What are micros?\") of the currency unit.", "type": "string", "format": "int64" } } }, "GenerateDeviceCaptureTokenResponse": { "description": "Response object for the generateDeviceCaptureToken method.", "type": "object", "properties": { "responseHeader": { "description": "**REQUIRED**: Common header for all responses.", "$ref": "#/definitions/ResponseHeader" }, "paymentIntegratorTransactionId": { "description": "**OPTIONAL**: This identifier is specific to the integrator and is generated by the integrator. This is the identifier that the integrator knows this transaction by. For convenience, this identifier is included with in the remittance details", "type": "string" }, "deviceCaptureToken": { "description": "**OPTIONAL**: Token to be presented to the device to trigger a capture completion. This value is **required** if the `result` is `SUCCESS` and should not be set if the result is anything other than `SUCCESS`.", "type": "string" }, "result": { "description": "**REQUIRED**: The result of the generate device capture token call. The non-success result codes indicate that there is no need to attempt a device capture since it is guaranteed to be declined based on the state of the user's account and this transactions details.", "$ref": "#/definitions/GenerateDeviceCaptureTokenResult" } } }, "GenerateDeviceCaptureTokenResult": { "description": "Information about the result of generating a device capture token.", "type": "object", "properties": { "generateDeviceCaptureTokenResultCode": { "description": "**REQUIRED**: Result code of this generate device capture token call.", "type": "string", "enum": [ "UNKNOWN_RESULT", "SUCCESS", "CHARGE_UNDER_TRANSACTION_LIMIT", "CHARGE_EXCEEDS_TRANSACTION_LIMIT", "CHARGE_EXCEEDS_DAILY_LIMIT", "CHARGE_EXCEEDS_MONTHLY_LIMIT", "ACCOUNT_CLOSED", "ACCOUNT_CLOSED_ACCOUNT_TAKEN_OVER", "ACCOUNT_CLOSED_FRAUD", "ACCOUNT_ON_HOLD", "INSUFFICIENT_FUNDS" ] }, "transactionMaxLimit": { "description": "If `generateDeviceCaptureTokenResultCode` is `CHARGE_EXCEEDS_TRANSACTION_LIMIT` then this is the value of the maximum allowable transaction. This is used for structured, user facing messaging and decline rate analysis. This amount is micros\/[micros]({{glossary_path}}#micros \"What are micros?\") of the same `currencyCode` as the original `generateDeviceCaptureToken` method call.", "type": "string", "format": "int64" }, "transactionMinLimit": { "description": "If `generateDeviceCaptureTokenResultCode` is `CHARGE_UNDER_TRANSACTION_LIMIT` then this is the value of the minimum allowable transaction. This is used for structured, user facing messaging and decline rate analysis. This amount is micros\/[micros]({{glossary_path}}#micros \"What are micros?\") of the same `currencyCode` as the original `generateDeviceCaptureToken` method call.", "type": "string", "format": "int64" } } }, "GetDeviceCaptureResultRequest": { "description": "Request object for the getDeviceCaptureResult method.", "type": "object", "properties": { "requestHeader": { "description": "**REQUIRED**: Common header for all requests.", "$ref": "#/definitions/RequestHeader" }, "paymentIntegratorAccountId": { "description": "**REQUIRED**: This is the payment integrator account identifier that identifies contractual constraints around this transaction.", "type": "string" }, "deviceCaptureRequestId": { "description": "**REQUIRED**: A unique identifier for this transaction that is a reference to the requestId provided at generateDeviceCaptureToken time.", "type": "string" } } }, "GetDeviceCaptureResultResponse": { "description": "Response object for the getDeviceCaptureResult method.", "type": "object", "properties": { "responseHeader": { "description": "**REQUIRED**: Common header for all responses.", "$ref": "#/definitions/ResponseHeader" }, "result": { "description": "**REQUIRED**: The result of this API call. This result is not the same as the device capture's result; this is an indicator of whether the integrator was able to successfully determine\/look up the device capture's result. A `SUCCESS` in this result does not necessarily mean the device capture itself was successful.", "type": "string", "enum": [ "UNKNOWN_RESULT", "SUCCESS" ] }, "deviceCaptureResult": { "description": "**REQUIRED**: The result of the device capture attempt.", "$ref": "#/definitions/DeviceCaptureResult" } } }, "DeviceCaptureResult": { "description": "Information about the final result of a device capture.", "type": "object", "properties": { "deviceCaptureResultCode": { "description": "**REQUIRED**: Result code of this device capture.", "type": "string", "enum": [ "UNKNOWN_RESULT", "SUCCESS", "CHARGE_UNDER_TRANSACTION_LIMIT", "CHARGE_EXCEEDS_TRANSACTION_LIMIT", "CHARGE_EXCEEDS_DAILY_LIMIT", "CHARGE_EXCEEDS_MONTHLY_LIMIT", "ACCOUNT_CLOSED", "ACCOUNT_CLOSED_ACCOUNT_TAKEN_OVER", "ACCOUNT_CLOSED_FRAUD", "ACCOUNT_ON_HOLD", "INSUFFICIENT_FUNDS" ] }, "transactionMaxLimit": { "description": "If `deviceCaptureResultCode` is `CHARGE_EXCEEDS_TRANSACTION_LIMIT` then this is the value of the maximum allowable transaction. This is used for structured, user facing messaging and decline rate analysis. This amount is micros of the same `currencyCode` as the original `generateDeviceCaptureToken` method call.", "type": "string", "format": "int64" }, "transactionMinLimit": { "description": "If `deviceCaptureResultCode` is `CHARGE_UNDER_TRANSACTION_LIMIT` then this is the value of the minimum allowable transaction. This is used for structured, user facing messaging and decline rate analysis. This amount is micros of the same `currencyCode` as the original `generateDeviceCaptureToken` method call.", "type": "string", "format": "int64" } } } } }