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] Copyright 2014-2016 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. Table of Contents 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 Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 1 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 Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 2 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. Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 3 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. Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 4 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. 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 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. 1 https://www.pcisecuritystandards.org/documents/SAQ_A-EP_v3.pdf ​ Copyright 2014-2017 GoInterpay, Inc. All Rights Reserved. Proprietary & Confidential. Shared with Merchant Clients. 5 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.