Gointerpay Checkout API Guide Technical Specification

GoInterpay Checkout API Guide Technical Specification

Gointerpay Checkout API Specification v2 Revision 018 February 2017

gointerpay.com docs.gointerpay.net

Questions and Comments: [email protected]

Table of Contents

Changes From Revision 017

Notifications Order Notification Structure Contract Notification Structure

Common Structures POST Request Error Consumer Consignee Card Details Action Return from Redirect

Checkout API Requests fingerprint badge localize getRates getPaymentMethods create checkout openContract modify authorize capture cancel refund query

Changes From Revision 017

Context Notes checkout, localize Clarified precision of ConsumerPrice. getRates, localize Added Rates array for non-guaranteed market rates. authorize Added DeviceFingerprint, ViaAgent, OpenContract, and ContractId. checkout Simplified shipping structure. create Added to create the order in GoInterpay separately from submitting payment details. openContract Added to simplify creation of contracts not related to an initial purchase. badge Added for access to required location declaration data on checkout pages. https://docs.gointerpay.net/display/PUB/Location+Declaration

Notifications For a list of notifications and order states please refer to the States & Events page at https://docs.gointerpay.net/display/PUB/States+and+Events. Notifications are sent via HTTP POST to a merchant-specified URL. The content of the HTTP POST is signed JSON which must be validated against the signature as follows: 1. Compute the SHA-256 HMAC value of the JSON entity using the shared secret; 2. Base-64 encode the result, and compare this to the specified Signature header.

GoInterpay considers a notification delivered when it receives an HTTP 200 OK response. Notifications are re-sent until an HTTP 200 OK response is received. The HTTP Date header specifies the date and time the notification was generated. If a notification is received out of order or is unknown, the merchant should still produce an HTTP 200 OK but ignore the notification.

Order Notification Structure

Field Type Required Notes

OrderId uuid Yes The GoInterpay order identifier returned in the checkout response, identifying the order for the notification.

ReferenceId string No The reference ID passed in in the original checkout request. UnderReview boolean Yes Set to true if a fraud review is in progress for the order. Payment cannot be processed until the review has been completed. Note that this is only applicable if the order has not failed or been cancelled.

OrderState string Yes See documentation on Order States above.

Refunds array No An array of refund data for refunds associated with the order.

RefundId uuid Yes The external uuid of the refund assigned by GoInterpay.

ReferenceId string Yes The reference id passed in by the merchant in the refund request.

State string Yes See documentation on Refund States above.

Contract Notification Structure

Field Type Required Notes

ContractId uuid Yes The GoInterpay contract identifier returned in the openContract response. ReferenceId string No The reference ID passed in in the original openContract request.

ContractState string Yes See documentation on Contract States above.

Common Structures The following structures are used in many requests in the API.

POST Request Error If there was an error when processing a POST request this is the error structure returned.

Field Type Required Notes

Code string Yes A request-specific error code, described in the Error Codes section for the specific request.

Message string No A short description of the error.

Consumer A Consumer is the person paying for an order and is sometimes referred to as a the billing contact. This information must match the address on file for the payment method used.

Field Type Required Notes

Name string Yes The consumer’s full name.

Company string No

Email string Yes

Phone string Maybe Ideally specified using E.164 formatting, but this is not enforced. This is required for some payment methods and/or countries.

Address string Yes The consumer’s street address.

City string Yes The city associated with the consumer’s address.

Region string Maybe The ISO-3166-2 subdivision code for the region (state, province, etc.) associated with the consumer’s address, not including the country code or dash. (eg NS, not CA-NS). This field may be omitted if there are no states/regions in the specified country.

PostalCode string Maybe The postal code associated with the consumer’s address. This field may be omitted if there are no postal codes in the specified country.

Country char(2) Yes The upper-case ISO 3166 alpha-2 country code associated with the consumer’s address.

NationalIdentifier string Maybe The country-specific unique identifier of the consumer, without punctuation. It is required to be present for the consumer used for some payment methods and/or countries. In cases where this is required, this is commonly related to taxes. Examples are SSN for the United States, SIN for Canada and CPF for Brazil. Note that if a Company is specified, this is the identifier of the company if applicable, for example the CPNJ in Brazil.

BirthDate string Maybe Required for some payment methods and/or countries. Must be specified as YYYY-MM-DD. MerchantProfileId string No The merchant’s identifier for the consumer’s profile. If submitted, this will link the consumer’s orders within GoInterpay for use in fraud analysis.

IpAddress string Maybe If the request does not originate from the consumer’s browser and ViaAgent is false, the IP address of the consumer must be specified either here or in a subsequent authorize or modify request.

Consignee A consignee is the person receiving an order. This is sometimes referred to as the shipping contact.

Field Type Required Notes

Name string Yes The consignee’s full name.

Company string No

Email string No

Phone string No Ideally specified using E.164 formatting, but this is not enforced.

Address string Yes The consignee’s street address.

City string Yes The city associated with the consignee’s address.

PostalCode string Maybe The postal code associated with the consignee’s address. This field may be omitted if there are no postal codes in the specified country.

Country char(2) Yes The upper-case ISO 3166 alpha-2 country code associated with the consignee’s address.

Card Details If the merchant adheres to the requirements of PCI DSS SAQ-A-EP1, card details may be added to the checkout, authorize, and/or openContract request in the card query string parameter, separate from the main request body. Consequently, the card details are not included in the signature calculation.

Field Type Required Notes

Number string Yes The card number, without punctuation or whitespace.

Name string Yes The name of the cardholder as it appears on the card.

Expiry object Yes The expiration date of the card.

Year integer Yes The expiry year, unabbreviated (ex. 2020).

Month integer Yes The expiry month.

2 VerificationCode string Yes The card verification code.

Action If additional action must be table to proceed with a request, this object contains information about the required action.

Field Type Required Notes

Redirect URL No The consumer must be redirected to the URL specified to complete the request. TODO: note about Return?

Display object No A freeform JSON object which, in the context of the specified request, gives the necessary information for a consumer to proceed. See the Display Parameters section.

Return from Redirect After the consumer has interacted with the site specified in a Redirect URL, their browser is redirected to the Return URL specified in the original request. The response and signature query parameters are appended to this URL. The response contains the following JSON-encoded data.

Field Type Required Notes

Error object Yes If present, the order could not be authorized due to an error. See POST Request Error -or-

OrderId uuid Yes The 36 character UUID which identifies the order in the GoInterpay system.

ContractId uuid No The contract identifier, if the order is associated with a contract.

UnderReview boolean No Set to true if a fraud review has been initiated for the order. Payment cannot be processed until the review has been completed. If not present, assume false. OrderState string Yes See documentation on Order States above. Captured boolean No An indication of the whether or not the payment has been captured and therefore completed. A notification will be sent when payment has completed regardless of the value of this field. If not present, assume false.

2 Although these are typically strings of digits, leading zeros are allowed and are better transmitted as a string. Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 6

Checkout API Requests

fingerprint Collect a device fingerprint from the shopper’s browser via an HTML script tag.

Request Parameters

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

Response This script tag returns Javascript that both inserts device detection HTML into the DOM and sets a global Javascript variable (gip_device_fingerprint) that is utilized in the checkout request.

Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 7 badge Retrieve location declaration information from GoInterpay. For more information see https://docs.gointerpay.net/display/PUB/Location+Declaration. Request Parameters

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

Callback string No The JSONP Javascript function to call.

Currency char(2) No If the consumer currency to be used is already known, the upper-case 3 character ISO 4217 currency code.

ConsumerIpAddress string No This parameter can be specified if the request is being made on behalf of the consumer, not directly via the consumer’s browser.

Response Structure Either the text or image should be displayed and linked to the TermsOfServiceUrl.

Field Type Required Notes

Text string Yes The text to display.

ImageUrl url Yes The image to display.

TermsOfServiceUrl url Yes The location that the text or image should link to.

Request Parameters With Currency

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

Callback string No The JSONP Javascript function to call.

Currency char(2) No The upper-case 3 character ISO 4217 currency code to get the symbol and units for, if available.

Response Structure

Field Type Required Notes

Currency char(2) Yes The upper-case 3 character ISO 4217 currency code submitted with localize. Symbol string No The symbol for the currency, if applicable (e.g. $, £, Kč).

Units integer Yes The number of minor units to display for the currency. Note that only two decimal places may be specified to checkout. Request Parameters Without Currency

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

Callback string No The JSONP Javascript function to call.

Country char(2) No If the merchant already knows the consumer’s country, the ISO 3166-1-alpha-2 can be passed in to fetch the localization data for that country. If this is specified, the GEO-IP lookup will be bypassed.

IncludeRate boolean No If true, the latest rate offer will be returned. If not included, or false, a rate offer will not be returned.

ConsumerIpAddress string No This parameter can be specified if the request is being made on behalf of the consumer, not directly via the consumer’s browser. If a Country is specified, this is ignored. Response Structure

Field Type Required Notes

Country char(2) Yes The upper-case 2 character ISO 3166-1-alpha-2 country code detected for the shopper, unless Country is specified.

Currency char(3) No The upper-case 3 character ISO 4217 currency code for the default currency for the country. The currency, and the associated information below, will only be returned if

supported by GoInterpay.

Symbol string No The symbol for the currency, if applicable (e.g. $, £, Kč).

Units integer Yes* The number of minor units to display for the currency. Note that up to two decimal places may be specified to checkout. RateOffer array No† The current rate offer available for specified currency. Id uuid Yes A GoInterpay rate offer ID for the merchant that can be used until the specified Expiry. Expiry string Yes The RFC 3339 timestamp at which this rate offer expires.

Rate decimal Yes The GoInterpay guaranteed exchange rate.

Rate decimal No† The current non-guaranteed market rate for the specified currency, if a guaranteed rate is not available. * Returned only if a Currency is returned. † Returned only if a Currency is returned and IncludeRate is true.

Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 10 getRates Fetches the list of current foreign exchange rate offers that are available to the merchant.

The returned foreign exchange rates are only guaranteed up to the expiry time specified— typically 24 hours. Attempting to create an order using an expired foreign exchange rate will result in an error. To avoid confusion it is recommended to call getRates several times per day. Request Parameters

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

Callback string No The JSONP Javascript function to call.

Response Structure

Field Type Required Notes

RateOffers array No An array of rate offers, if guaranteed rates are available.

Id uuid Yes A GoInterpay rate offer ID for the merchant that can be used until the specified Expiry. Currency char(3) Yes The upper-case 3 character ISO 4217 currency code for this rate offer.

Expiry string Yes The RFC 3339 timestamp at which this rate offer expires.

Rate decimal Yes The GoInterpay guaranteed exchange rate.

Rates array No An array of non-guaranteed market rates, if guaranteed rates are not available.

Currency char(3) Yes The upper-case 3 character ISO 4217 currency code for this rate offer.

Rate decimal Yes The approximate market exchange rate, updated daily.

Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 11 getPaymentMethods Retrieve available payment methods for the specified currency and country.

Request Parameters

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

Country char(2) Yes Upper-case 2 character ISO 3166-1-alpha-2 country code. Only methods available to this country will be returned.

Currency char(3) Yes Upper-case 3 character ISO 4217 currency code. Only methods available to this currency will be returned.

ViaAgent boolean No If true, only payment methods able to be completed via an agent will be returned.

Callback string No The JSONP Javascript function to call.

Response Structure

Field Type Required Notes

PaymentMethods array of Yes An array containing information about the payment methods objects available to the specified Country and Currency (and possibly the ViaAgent flag) Id string Yes The GoInterpay canonical name of the payment method.

Name string Yes The industry accepted name of the payment method. For example: ‘MasterCard’.

Local boolean No If present and true, this payment method is considered local to the country specified in the request and may have better conversion if presented prominently to the shopper.

Class enum Yes The class of the payment method will be one of the following: Card - (ex: VISA, MC) Offline - (ex: BOLETO, BANK) Online - (ex: PAYPAL, EFT) Financing boolean No If present and true, financing options (detailed below) are available if payment is made using this method.

Issuers array of No An array of issuers that may be associated with this payment objects method. Typically, these identify banks or other institutions that issue payment products. If present, an issuer must be selected from this list to use this payment method.

Id string Yes The GoInterpay canonical name of the issuer. For example: ‘AhorroFamsa’ Name string Yes A human readable name for the issuer. For example: ‘Banco Ahorro Famsa’.

Financing object No If financing options are available for any of the payment methods returned, the options will be listed here.

Instalments array of No The financing information associated with payment via objects instalments.

Number integer Yes The number of instalments in which the payment will be made.

Rate decimal Yes The rate by which the total amount, excluding financing, should be multiplied to determine the financing fees.

Request Structure

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

ReferenceId string No An optional string identifying the order in the merchant’s order management system. If specified, this is returned in the notification of a processed order, so that the merchant’s system can cross-reference the GoInterpay order with the merchant’s order data.

DeviceFingerprint string No The device fingerprint as returned by GoInterpay from the fingerprint request. ConsumerCurrency char(3) Maybe The upper-case 3 character ISO 4217 currency code which the shopper has indicated is their preferred currency. Required if RateOfferId is not specified.

Country char(2) Maybe The upper-case 2 character ISO 3166-1-alpha-2 country code which the shopper has indicated is their preferred country.

Required if the country is not specified in the Consumer object below and GoInterpay is not retrieving the country during the checkout process (ex. via PayPal).

RateOfferId uuid No The 36 character GUID for a guaranteed foreign exchange rate. If omitted, the rate will be determined at the time of settlement.

Items array Yes An array of objects containing information for each product in the shopper’s order.

Sku string Yes The merchant’s Stock Keeping Unit for the item.

ConsumerPrice decimal Yes The unit price of the item expressed in the consumer currency. This, combined with the Quantity, is used to produce the total item value. Prices with up to two decimal places of precision are supported. Quantity decimal Yes

Description string No

ImageUrl string No

Shipping object No If physical shipping of goods is required for this order, Shipping must be specified before authorization. ConsumerPrice decimal Yes The amount, including all service fees, surcharges, etc, but excluding taxes and duty, associated with the physical shipping option. ConsumerTaxes decimal Yes

ConsumerDuty decimal Yes

Charges array No An optional array of objects containing additional charges associated with this order. The sum of all charges will be added to the total amount charged to the consumer.

Name string Yes

ConsumerPrice decimal Yes The consumer price associated with the charge.

Discounts array No An optional array of objects containing discounts associated with this order. The sum of all discounts will be subtracted from the total amount charged to the consumer. Name string Yes

ConsumerPrice decimal Yes The consumer price associated with the discount. Note that since this amount is subtracted from the total amount charged to the consumer, it should not be negative. Financing object No Must be included if a financing option is selected by the consumer.

Instalments integer Yes The number of instalments in which the full amount will be charged.

ConsumerPrice decimal Yes The consumer price charged to the consumer for the financing option, independent of the financing charge to the merchant returned by getPaymentMethods. ConsumerTotal decimal No If specified, this serves as a check to ensure that the total amount charged to the consumer is as specified. The sum of all items and charges, plus the total amount associated with shipping (if applicable) minus the sum of all discounts, plus the financing price, must be equal to this amount.

Consumer object No Consumer must be specified or collected before authorization. If not specified, it will be collected during authentication, if possible. If the request does not originate from the consumer’s browser and payment details will be provided by the consumer, the IP address of the consumer must be specified either here or in a subsequent authorize or modify request. Consignee object No An object containing information about the consignee for the order. Consignee must be specified or collected before authorization if Shipping is present. If not specified and required, it will be collected during authentication if possible. This field is not allowed if Shipping is not present. AcceptLiability boolean No If true, the merchant accepts financial liability for this order. This is typically used for VIP or otherwise whitelisted consumers.

Store string No An optional tag that can be used to categorize orders. Typically used when a merchant has multiple storefronts on their website but wishes to use the same GoInterpay Merchant Id.

Return URL Maybe The URL to which the consumer’s browser will be redirected after external authentication (if necessary) has completed. See Return from Redirect. Notify URL No An optional URL that will override the default notification URL configured for the merchant. All notifications related to this order, including refunds, will go to this override.

Locale string No If known, the preferred locale of the consumer specified as an BCP 47 IETF language tag, as seen, for example, in an HTTP Accept-Language header. Extensions such as RFC 6067 Unicode Locale are accepted.

Meta JSON No An opaque JSON value (string, number, boolean, array, or object) which is returned to the merchant in response to a query request for this order. Response Structure

Field Type Required Notes

Error object Yes If present, the order could not be created due to an error. See POST Request Error

-or-

OrderId uuid Yes The 36 character UUID which identifies the order in the GoInterpay system.

Expiry string No The RFC 3339 time by which authorization must be completed.

Error Codes

Code Description

RateOfferNotFound The RateOfferId did not identify a known, non-expired GoInterpay rate offer. CurrencyNotFound The ConsumerCurrency did not correspond to a supported GoInterpay currency.

CurrencyMismatch The ConsumerCurrency specified in the request did not match the Currency associated with the specified GoInterpay rate offer.

PaymentMethodUnsupported The PaymentMethod is either not supported by GoInterpay or the merchant has not been approved to use it.

ConsumerTotalInvalid The ConsumerTotal is not correct.

Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 16 checkout Creates a merchant’s order within GoInterpay and attempts authorization of the payment. Since this call may contain cardholder data it must be made directly from the shopper’s browser unless the Merchant is PCI DSS Level 1 compliant.

Request Structure

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

DeviceFingerprint string Maybe The device fingerprint as returned by GoInterpay from the fingerprint request. This is not required if ViaAgent is true. ConsumerCurrency char(3) Yes The upper-case 3 character ISO 4217 currency code which the shopper has indicated is their preferred currency.

Country char(2) Maybe The upper-case 2 character ISO 3166-1-alpha-2 country code which the shopper has indicated is their preferred country.

Required if the country is not specified in the Consumer object below and GoInterpay is not retrieving the country during the checkout process (ex. via PayPal).

RateOfferId uuid No The 36 character GUID for a guaranteed foreign exchange rate. If omitted, the rate will be determined at the time of settlement and all prices and breakdowns must be specified in the consumer currency.

Items array Yes An array of objects containing information for each product in the shopper’s order.

Sku string Yes The merchant’s Stock Keeping Unit for the item.

Description string No

ImageUrl string No

Shipping object No If physical shipping of goods is required for this order, Shipping must be specified. ConsumerPrice decimal Yes The amount, including all service fees, surcharges, etc, but excluding taxes and duty, associated with physical shipping.

ConsumerTaxes decimal Yes Taxes incurred for the entire order.

ConsumerDuty decimal Yes Duty incurred for the entire order.

Charges array No An optional array of objects containing additional charges associated with this order. The sum of all charges will be added to the total amount charged to the consumer. Name string Yes

ConsumerPrice decimal Yes The consumer price associated with the charge.

Instalments integer Yes The number of instalments in which the full amount will be charged.

ConsumerPrice decimal Yes The price charged to the consumer for the financing option, independent of the financing charge to the merchant returned by getPaymentMethods. Specified in the consumer currency. ConsumerTotal decimal No If specified, this serves as a check to ensure that the total amount charged to the consumer is as specified. The sum of all items and charges, plus the total amount associated with the selected shipping option (if applicable) minus the sum of all discounts, plus the financing price, must be equal to this amount.

Consumer object Yes See Consumer Common Structure above. Consignee object Maybe See Consignee Common Structure above. Consignee must be specified if Shipping is present. ViaAgent boolean No Indicates that this order is being made by an agent, and not the end consumer. If false or not present, the order is assumed to be placed by the end consumer.

Note that to submit payment card transactions via an agent, a 3 merchant must submit a PCI DSS SAQ-C-VT to GoInterpay. AcceptLiability boolean No If true, the merchant accepts financial liability for this order. This is typically used for VIP or otherwise whitelisted consumers.

Capture boolean No If true or the payment method used by the consumer does not support pre-authorization, the payment will be completed. If false or not present, and the payment method supports pre-authorization, the order will be left in the PaymentAuthorized state and the merchant must capture the order using a capture request. OpenContract boolean No If true, a contract (used for recurring billing, subscriptions, stored payment options, etc.) will be opened if possible. If false or not present, the order will not open a contract. To open a contract without an initial order, please see openContract.

ContractId uuid No If a contract was created in a previous order (using the OpenContract flag) or through a call to openContract, the returned ContractId can be used here instead of submitting payment information again to make a new order.

Store string No An optional tag that can be used to categorize orders. Typically used when a merchant has multiple storefronts on their website but wishes to use the same GoInterpay Merchant Id.

PaymentMethod string Maybe The GoInterpay canonical name of the payment method to be used as returned in the getPaymentMethods response. Must be specified if ContractId is not provided. IssuerId string Maybe If a list of issuers is returned by a previous call to getPaymentMethods for the specified PaymentMethod, this must contain the GoInterpay canonical name of the selected issuer.

Meta JSON No An opaque JSON value (string, number, boolean, array, or object) which is returned to the merchant in response to a query request for this order.

Response Structure

Field Type Required Notes

Error object Yes If present, the order could not be created or authorized due to an error. See POST Request Error -or-

OrderId uuid Yes The 36 character UUID which identifies the order in the GoInterpay system.

UnderReview boolean No Set to true if a fraud review has been initiated for the order. Payment cannot be processed until the review has been completed. If Capture is true, once the order is approved, capture will occur and the merchant will receive notification. If not present, assume false.

Expiry string No If further authentication is required, this is the RFC 3339 time by which authentication must be completed.

If the shopper is authenticated but the order is not authorized, this is the RFC 3339 time by which authorization must be completed.

If the order is created and authorized but not captured this is the RFC 3339 time by which this order must be captured.

ContractId uuid No If OpenContract was specified in the request to checkout and a contract was successfully created, this is the GoInterpay 36 character UUID which identifies the contract and can be used in future orders for this consumer.

Authorized boolean Yes An indication of the whether or not the payment has been authorized.

Captured boolean No An indication of the whether or not the payment has been captured and therefore completed. If Capture was true in the request to checkout, and this field is false, the capture is still in progress. A notification will be sent when payment has completed regardless of the value of this field. If not present, assume false.

Action object No See Action.

Error Codes

Code Description

RateOfferNotFound The RateOfferId did not identify a known, non-expired GoInterpay rate offer. CurrencyNotFound The ConsumerCurrency did not correspond to a supported GoInterpay currency.

CurrencyMismatch The ConsumerCurrency specified in the request did not match the Currency associated with the specified GoInterpay rate offer.

EmailAddressInvalid The consumer Email was either invalid or not supplied when required. PaymentMethodUnsupported The PaymentMethod is either not supported by GoInterpay or the merchant has not been approved to use it.

CardNameInvalid The Name in the card details was not valid. CardNumberInvalid The Number in the card details was not valid for the specified payment method. CardYearInvalid The Year in the card details was not valid. CardMonthInvalid The Month in the card details was not valid. CardExpired The specified payment card has expired.

CardVerificationCodeInvalid The VerificationCode in the card details was not valid. PostalCodeInvalid The consumer PostalCode was either invalid or not supplied when required. CountryInvalid The consumer Country was either invalid or not supplied when required. AmountInvalid A ConsumerPrice did not meet the requirements documented for the request. AmountLimitExceeded The request contains an amount that exceeds the amount that GoInterpay is willing to transact in a single order for the merchant.

PaymentAuthorizationFailed The payment processing provider, or an intermediary, refused to authorize the payment despite the details being syntactically correct. For example, the payment processor’s fraud checks may have failed or the payment processor may have been unable to validate authentication.

Blacklisted The consumer is on the GoInterpay blacklist and GoInterpay has refused to process the order.

FraudSuspected Based on the parameters of the order, GoInterpay suspects that the order is fraudulent and/or represents too high a risk to proceed with processing.

ContractNotFound The specified ContractId is not associated with the requesting Merchant. ContractClosed The specified ContractId is closed and cannot be used to begin new orders. InstalmentsInvalid A Number was specified for Instalments which is not between 2 and 12. InstalmentsNotAvailable Instalments were specified, but are not available for the specified card.

BirthDateInvalid The consumer BirthDate was either invalid or not supplied when required. NationalIdentifierInvalid The consumer NationalIdentifier was either invalid or not supplied when required.

PhoneInvalid The consumer Phone was either invalid or not supplied when required. RegionInvalid The consumer Region was either invalid or not supplied when required.

InvalidSpotTrade The merchant is not configured to perform a spot trade.

CaptureInvalid The specified value of Capture is not valid for the payment method. ConsumerTotalInvalid The ConsumerTotal is not correct. Return Error Codes

Code Description

PaymentAuthorizationFailed The payment could not be authorized after the consumer returned from the external site.

PaymentAuthenticationCancelled The consumer cancelled payment on the external site.

AlreadyCancelled The order was cancelled before the consumer completed authentication.

PaymentFailed The payment was authorized but could not be captured.

openContract Creates a contract within GoInterpay. Since this call may contain cardholder data it must be made directly from the shopper’s browser unless the Merchant is PCI DSS Level 1 compliant. Unless otherwise specified, the requirements of each field is the same as specified in checkout above. Request Structure

Field Type Required Notes

MerchantId uuid Yes

ReferenceId string No

DeviceFingerprint string Maybe

ConsumerCurrency char(3) Yes

Consumer object No

ViaAgent boolean No

AcceptLiability boolean No

PaymentMethod string Yes

IssuerId string Maybe

Return URL Maybe

Notify URL No

Locale string No

Response Structure

Field Type Required Notes

Error object Yes If present, a contract could not be created due to an error. See POST Request Error

-or-

ContractId uuid No This is the GoInterpay 36 character UUID which identifies the contract and can be used in future orders for this consumer. This may not be present if the consumer must be redirected to completed creation of the contract.

Action object No See Action.

Error Codes

Code Description

RateOfferNotFound The RateOfferId did not identify a known, non-expired GoInterpay rate offer. CurrencyNotFound The ConsumerCurrency did not correspond to a supported GoInterpay currency.

CurrencyMismatch The ConsumerCurrency specified in the request did not match the Currency associated with the specified GoInterpay rate offer.

CardVerificationCodeInvalid The VerificationCode in the card details was not valid. PostalCodeInvalid The consumer PostalCode was either invalid or not supplied when required. CountryInvalid The consumer Country was either invalid or not supplied when required. PaymentAuthorizationFailed The payment processing provider, or an intermediary, refused to authorize the payment despite the details being syntactically correct. For example, the payment processor’s fraud checks may have failed or the payment processor may have been unable to validate authentication.

Blacklisted The consumer is on the GoInterpay blacklist and GoInterpay has refused to process the order.

FraudSuspected Based on the parameters of the order, GoInterpay suspects that the order is fraudulent and/or represents too high a risk to proceed with processing.

InstalmentsNotAvailable Instalments were specified, but are not available for the specified card.

BirthDateInvalid The consumer BirthDate was either invalid or not supplied when required. NationalIdentifierInvalid The consumer NationalIdentifier was either invalid or not supplied when required.

PhoneInvalid The consumer Phone was either invalid or not supplied when required. RegionInvalid The consumer Region was either invalid or not supplied when required.

InvalidSpotTrade The merchant is not configured to perform a spot trade.

Return Error Codes

Code Description

PaymentAuthorizationFailed The payment could not be authorized after the consumer returned from the external site.

PaymentAuthenticationCancelled The consumer cancelled payment on the external site.

AlreadyCancelled The order was cancelled before the consumer completed authentication.

PaymentFailed The payment was authorized but could not be captured.

Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 24 modify Modify an order before capture has been initiated. Some fields may only be modified before authorization, as indicated below. After authorization, the total amount of the order may not exceed the authorized amount.

This request should not be called directly from the shopper’s browser.

Request Structure Unless otherwise specified, these fields have the same meaning as the corresponding fields in checkout. Values specified in the modify request replace any previous values. Unspecified fields remain unchanged in the order. Fields specified as null are removed from the order.

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

OrderId uuid Yes The GoInterpay order identifier returned in the checkout response. RateOfferId uuid No*

Items array No

Shipping object No

Charges array No

Discounts array No

Financing object No Only the Financing price may be modified, not the number of instalments.

ConsumerTotal decimal No As described for the checkout request, this serves as an optional check to ensure that the total amount charged to the consumer is as specified. This uses the most recent values for all fields, including those specified in this modify request. Consumer object No* Once set with create, checkout, or modify, the Consumer may not be changed. Consignee object No*

AcceptLiability boolean No*

Locale string No*

Meta JSON No * may only be modified before payment has authorized.

Response Structure

Field Type Required Notes

Error object Yes If present, the order could not be modified due to an error. See POST Request Error

-or-

OrderId uuid Yes The GoInterpay order identifier specified in the request.

Error Codes

Code Description

RateOfferNotFound The RateOfferId did not identify a known, non-expired GoInterpay rate offer. CurrencyNotFound The ConsumerCurrency did not correspond to a supported GoInterpay currency. CurrencyMismatch The ConsumerCurrency specified in the request did not match the currency associated with the order.

EmailAddressInvalid The consumer Email was either invalid or not supplied when required. PostalCodeInvalid The consumer PostalCode was either invalid or not supplied when required. CountryInvalid The consumer Country was either invalid or not supplied when required. AmountInvalid A ConsumerPrice did not meet the requirements documented for the request. InstalmentsInvalid A Number was specified for Instalments which is not between 2 and 12 (inclusive) or instalments are not available for this order.

BirthDateInvalid The consumer BirthDate was either invalid or not supplied when required. NationalIdentifierInvalid The consumer NationalIdentifier was either invalid or not supplied when required.

PhoneInvalid The consumer Phone was either invalid or not supplied when required. RegionInvalid The consumer Region was either invalid or not supplied when required.

InvalidTotal The consumer total was greater than the amount authorized.

authorize

Authorize payment for an order. This requires that the specified order has been created but not authorized yet. Since this call may contain cardholder data it must be made directly from the shopper’s browser unless the Merchant is PCI DSS Level 1 compliant.

Request Structure

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

OrderId uuid Yes The GoInterpay order identifier returned in the checkout response.

PaymentMethod string No The GoInterpay canonical name of the payment method to be used, if different from previously specified.

IssuerId string Maybe If a list of issuers is returned by a previous call to getPaymentMethods for the specified PaymentMethod, this must contain the GoInterpay canonical name of the selected issuer.

ConsumerIpAddress string Maybe If the request does not originate from the consumer’s browser and ViaAgent is false, the IP address of the consumer must be specified here.

DeviceFingerprint string Maybe The device fingerprint as returned by GoInterpay from the fingerprint request. This is not required if ViaAgent is true. Return URL No The URL to which the consumer’s browser will be redirected after external authentication (if necessary) has completed. See Return from Redirect. ViaAgent boolean No Indicates that this order is being made by an agent, and not the end consumer. If false or not present, the order is assumed to be placed by the end consumer.

Note that to submit payment card transactions via an agent, a 4 merchant must submit a PCI DSS SAQ-C-VT to GoInterpay. OpenContract boolean No If true, a contract (used for recurring billing, subscriptions, stored payment options, etc.) will be opened if possible. If false or not present, the order will not open a contract. To open a contract without an initial order, please see openContract. ContractId uuid No If a contract was created in a previous order (using the OpenContract flag) or through a call to openContract, the returned ContractId can be used here instead of submitting payment information again to make a new order.

Response Structure

Field Type Required Notes

Error object Yes If present, the authorization could not be performed due to an error. See POST Request Error -or-

OrderId string Yes The GoInterpay order identifier specified in the request. uuid

Expiry string No If the order was authorized with Capture false, the RFC 3339 time at which this order expires.

Captured boolean No If true, the capture has successfully completed. If Capture was true in the request to checkout, and this field is false, the capture is still in progress A notification will be sent when payment has completed regardless of the value of this field. If not present, assume false.

ContractId string No If OpenContract was specified in the request to checkout uuid and a contract was successfully created, this is the GoInterpay 36 character UUID which identifies the contract, and can be used for subsequent related payments.

Action object No See Action. Error Codes

Code Description

AlreadyCancelled The GoInterpay order has automatically expired and cannot be authorized.

AlreadyDeclined The GoInterpay order has already been declined and cannot be authorized.

CardVerificationCodeInvalid The VerificationCode in the card details was not valid. PostalCodeInvalid The consumer PostalCode was invalid or not supplied when required. CountryInvalid The consumer Country was invalid or not supplied when required. AmountInvalid A ConsumerPrice did not meet the requirements documented for the request. AmountLimitExceeded The request contains an amount that exceeds the amount that GoInterpay is willing to transact in a single order for the merchant.

PaymentAuthorizationFailed The payment processing provider, or an intermediary, refused to authorize the payment despite the details being syntactically correct. For example, the payment

processor’s fraud checks may have failed or the payment processor may have been unable to validate authentication.

Blacklisted The consumer is on the GoInterpay blacklist and GoInterpay has refused to process the order.

FraudSuspected Based on the parameters of the order, GoInterpay suspects that the order is fraudulent and/or represents too high a risk to proceed with processing.

ContractClosed The specified ContractId is closed and cannot be used to begin new orders. BirthDateInvalid The consumer BirthDate was invalid or not supplied when required. NationalIdentifierInvalid The consumer NationalIdentifier was invalid or not supplied when required. PhoneInvalid The consumer Phone was invalid or not supplied when required. RegionInvalid The consumer Region was invalid or not supplied when required.

InstalmentsNotAvailable Instalments were requested in the call to checkout but are not available to the card specified.

CaptureInvalid The specified value of Capture is not valid for the payment method.

Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 29 capture Capture a pre-authorized order. This requires that the payment method support pre-authorization and the Capture flag to be false in the related checkout or authorize request. This request should not be called directly from the shopper’s browser.

Request Structure

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

OrderId uuid Yes The GoInterpay order identifier returned in the checkout response.

Response Structure

Field Type Required Notes

Error object Yes If present, the capture could not be performed due to an error. See POST Request Error -or-

OrderId uuid Yes The GoInterpay order identifier specified in the request.

Completed boolean Yes If true, the capture has successfully completed. If false, the capture is in progress and a notification will be sent when payment has completed.

Error Codes

Code Description

AlreadyCancelled The GoInterpay order has already been cancelled by the merchant or has automatically expired and cannot be captured.

PaymentFailed The payment transaction could not be captured for the order. This could be due to administrative or policy actions within GoInterpay, an error at the payment method provider, or other reasons. The Message element may contain additional information.

UnderReview The order is under review and may not be captured until the review has completed.

Blacklisted The consumer is on the GoInterpay blacklist and GoInterpay has refused to process the order.

FraudSuspected Based on the parameters of the order, GoInterpay suspects that the order is fraudulent and/or represents too high a risk to proceed with processing.

Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 30 cancel Cancel a pre-authorized order. This requires that payment has not been captured.

This request should not be called directly from the shopper’s browser.

Request Structure

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

OrderId uuid Yes The GoInterpay order identifier returned in the checkout response.

Response Structure

Field Type Required Notes

Error object Yes If present, the cancel could not be performed due to an error. See POST Request Error -or-

OrderId uuid Yes The GoInterpay order identifier specified in the request.

Error Codes

Code Description

AlreadyCaptured The GoInterpay order has already been captured by the merchant and cannot be cancelled.

AlreadyDeclined The GoInterpay order has already been declined and cannot be cancelled.

Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 31 refund Submit a full or partial refund for an order that has been captured. This request should not be called directly from the shopper’s browser.

Request Structure

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

OrderId uuid Yes The GoInterpay order identifier, returned in the checkout response, identifying the order to which the refund is to be applied.

ReferenceId string Yes An identifier the merchant wishes to associate with the refund. This must be unique within the context of the associated order. The prefix "INTERPAY" is reserved and cannot appear at the beginning of this identifier.

Amount decimal Yes The amount to refund, specified in the consumer’s currency. Must be less than or equal to the original order or contract amount, minus any refunds that have happened so far.

Response Structure

Field Type Required Notes

Error object Yes If present, the refund could not be performed due to an error. See POST Request Error -or-

OrderId uuid Yes The GoInterpay order or identifier specified in the request.

RefundId uuid Yes The GoInterpay Refund ID for the newly submitted refund.

Error Codes

Code Description

OrderStateInvalid The specified order is not in the correct state and therefore refunds cannot be registered against it.

TransactionStateInva The specified order is not in the correct state and therefore refunds cannot be registered lid against it.

AmountInvalid The Amount did not meet the requirements documented for the request. RefundLimitExceeded The refund could not be registered because doing so would cause the sum of refund amounts to exceed the original order amount.

ReferenceIdMismatch The ReferenceId specified in the request already exists for the order specified in the request and the remaining parameters do not match the existing refund.

ReferenceIdInvalid The ReferenceId is invalid because it begins with the reserved prefix. RefundPeriodEnded The period in which the merchant is allowed to submit refunds for the order has ended.

ChargebackExists A refund cannot be submitted because there is a chargeback issued against the order.

query Query order information from the GoInterpay system. If the order is not found, an HTTP 404 response will be returned. If there is a system problem with querying the order, an HTTP 503 response will be returned and the request should be tried again.

This request should never be called directly from the shopper’s browser.

Request Structure

Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system.

OrderId uuid* Yes The GoInterpay order identifier returned in the checkout -or- response, or a ReferenceId specified by the merchant in the ReferenceId checkout request. * If ReferenceId is specified, this is an unconstrained string. Response Structure (if OrderId specified) Unless otherwise specified, these have the same meaning as the corresponding fields in checkout. Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system. ReferenceId string No OrderId uuid Yes The unique identifier for the GoInterpay order. TransactionId uuid Yes The identifier for the GoInterpay payment transaction associated with the order. ContractId uuid No The identifier for the GoInterpay contract, if a contract was opened using the OpenContract option in checkout or authorize, or through the openContract request. RateOfferId uuid No The identifier for a guaranteed foreign exchange rate. If omitted, the rate will be determined at the time of settlement.

Rate decimal No The foreign exchange rate used for this order. If omitted, the rate will be determined at the time of settlement. UnderReview boolean Yes Set to true if a fraud review is in progress for the order. Payment cannot be processed until the review has been completed. Chargeback boolean Yes Set to true if a chargeback has been issued against the order. An outstanding chargeback disables the ability to submit a refund against the order. OrderState string Yes See documentation on Order States above. Reason string No A non-normative reason for the current state, if any. Expiry string Maybe If the order was created with Capture false, and the payment is authorized, the RFC 3339 time at which this order expires. If further authentication is required, this is the time by which that

authentication must be completed. Action object No See Action. Times object Yes Created string Yes The RFC 3339 timestamp at which the order was created. Authorized string No The RFC 3339 timestamp at which the order’s payment was authorized. This will be null if the payment has not yet been authorized or the payment method used for the order does not support pre-authorization (eg. Boleto). Processed string No The RFC 3339 timestamp at which the order’s payment was processed. This will be null if the order’s payment has not been processed yet or has failed to be processed. ConsumerCurrency string Yes Consumer object Yes Consignee object No Payment object No Most recently finished payment information regardless of success. This will not be present in an order for which payment has not been attempted. Method string Yes The GoInterpay canonical name of the payment method used. AccountIdentifier string No When a Card is used, this will be a truncated version of the payment card number. For non-Card methods, it will be the email address or other identifying string, if available. Items array Yes Sku string Yes Quantity decimal Yes MerchantPrice decimal Yes The price of the item in the merchant’s currency. ConsumerPrice decimal Yes Shipping object No MerchantBreakdown object Yes The shipping breakdown values in the merchant’s currency. ConsumerBreakdown object Yes Charges array No Name string Yes MerchantPrice decimal Yes The price of the charge in the merchant’s currency. ConsumerPrice decimal Yes Discounts array No Name string Yes MerchantPrice decimal Yes The value of the discount in the merchant’s currency. ConsumerPrice decimal Yes Financing object No Instalments integer Yes MerchantPrice decimal Yes The price of the financing option in the merchant’s currency.

ConsumerPrice decimal Yes MerchantTotal decimal Yes The total amount charged to the consumer in the merchant’s currency. Note that this includes all fees, which will not be remitted to the merchant. ConsumerTotal decimal Yes The total amount charged to the consumer in the consumer’s currency. Store string No Refunds array No If any refunds have been submitted for this order, details will appear in this array. RefundId uuid Yes The external uuid of the refund assigned by GoInterpay. ConsumerAmount decimal Yes The amount of the refund in the consumer currency. This amount may not be the total order amount if a partial refund has been submitted. However, the sum of all refund amounts will not exceed the total order amount. MerchantAmount decimal No The amount of the refund in the merchant currency. This will be null if the amount is not yet known. State string Yes See documentation on Refund States above. ReferenceId string Yes The reference id for this refund. StartTime string Yes The RFC 3339 timestamp at which the refund was created. ProcessedTime string Yes The RFC 3339 timestamp at which the refund was processed. Meta JSON No

Response Structure (if ReferenceId specified) Field Type Required Notes

MerchantId uuid Yes The 36 character GUID which identifies the merchant to the GoInterpay system. Orders array Yes An array (which may be empty) of GoInterpay order data for object orders whose reference matches the specified Reference. OrderId uuid Yes The GoInterpay order id for this order. OrderState string Yes See documentation on Order States above. Times object Yes Created string Yes The RFC 3339 timestamp at which the order was created.