--- swagger: "2.0" info: x-ibm-name: checkout-sandbox title: Checkout version: 2.0.0 description: 'The Checkout API includes two operations: Checkout Payment and Checkout Status. Checkout Payment performs a request to prepare the checkout required data and returns with the Payment Form. Checkout Status allows merchants to check the status of a specific payment.' schemes: - https basePath: /sibs/spg/v2 consumes: - application/json - text/plain produces: - application/json - text/plain securityDefinitions: clientid: type: apiKey description: "" in: header name: X-IBM-Client-Id x-ibm-configuration: testable: true enforced: true phase: realized paths: /payments: post: responses: 200: description: OK schema: $ref: '#/definitions/ReturnCheckout' 201: description: Created schema: $ref: '#/definitions/ReturnCheckout' 204: description: No Content schema: $ref: '#/definitions/ReturnCheckout' 206: description: Partial Content schema: $ref: '#/definitions/ReturnCheckout' 400: description: Bad Request. schema: $ref: '#/definitions/ReturnCheckout' 401: description: Unauthorized. schema: $ref: '#/definitions/ReturnCheckout' 403: description: Forbidden. schema: $ref: '#/definitions/ReturnCheckout' 404: description: Not Found. schema: $ref: '#/definitions/ReturnCheckout' 405: description: Method Not Allowed. schema: $ref: '#/definitions/ReturnCheckout' 406: description: Not Acceptable. schema: $ref: '#/definitions/ReturnCheckout' 408: description: Request Timeout. schema: $ref: '#/definitions/ReturnCheckout' 415: description: Unsupported Media Type. schema: $ref: '#/definitions/ReturnCheckout' 429: description: Too Many Requests. schema: $ref: '#/definitions/ReturnCheckout' 500: description: Internal Server Error. schema: $ref: '#/definitions/ReturnCheckout' 503: description: Service Unavailable. schema: $ref: '#/definitions/ReturnCheckout' 504: description: Gatewaty Timeout. schema: $ref: '#/definitions/ReturnCheckout' parameters: - name: input required: true in: body schema: $ref: '#/definitions/RequestCheckout' - $ref: '#/parameters/Authorization' - $ref: '#/parameters/Signature' operationId: checkout /payments/status: get: responses: 200: description: OK schema: $ref: '#/definitions/ResponseInquiry' 204: description: No Content schema: $ref: '#/definitions/ResponseInquiry' 206: description: Partial Content schema: $ref: '#/definitions/ResponseInquiry' 400: description: Bad Request. schema: $ref: '#/definitions/ResponseInquiry' 401: description: Unauthorized. schema: $ref: '#/definitions/ResponseInquiry' 403: description: Forbidden. schema: $ref: '#/definitions/ResponseInquiry' 404: description: Not Found. schema: $ref: '#/definitions/ResponseInquiry' 405: description: Method Not Allowed. schema: $ref: '#/definitions/ResponseInquiry' 406: description: Not Acceptable. schema: $ref: '#/definitions/ResponseInquiry' 408: description: Request Timeout. schema: $ref: '#/definitions/ResponseInquiry' 415: description: Unsupported Media Type. schema: $ref: '#/definitions/ResponseInquiry' 429: description: Too Many Requests. schema: $ref: '#/definitions/ResponseInquiry' 500: description: Internal Server Error. schema: $ref: '#/definitions/ResponseInquiry' 503: description: Service Unavailable. schema: $ref: '#/definitions/ResponseInquiry' 504: description: Gatewaty Timeout. schema: $ref: '#/definitions/ResponseInquiry' operationId: statusQuery parameters: - $ref: '#/parameters/Authorization' - $ref: '#/parameters/merchantTransactionId' - $ref: '#/parameters/Signature' /payments/{id}/status: get: responses: 200: description: OK schema: $ref: '#/definitions/ResponseInquiry' 204: description: No Content schema: $ref: '#/definitions/ResponseInquiry' 206: description: Partial Content schema: $ref: '#/definitions/ResponseInquiry' 400: description: Bad Request. schema: $ref: '#/definitions/ResponseInquiry' 401: description: Unauthorized. schema: $ref: '#/definitions/ResponseInquiry' 403: description: Forbidden. schema: $ref: '#/definitions/ResponseInquiry' 404: description: Not Found. schema: $ref: '#/definitions/ResponseInquiry' 405: description: Method Not Allowed. schema: $ref: '#/definitions/ResponseInquiry' 406: description: Not Acceptable. schema: $ref: '#/definitions/ResponseInquiry' 408: description: Request Timeout. schema: $ref: '#/definitions/ResponseInquiry' 415: description: Unsupported Media Type. schema: $ref: '#/definitions/ResponseInquiry' 429: description: Too Many Requests. schema: $ref: '#/definitions/ResponseInquiry' 500: description: Internal Server Error. schema: $ref: '#/definitions/ResponseInquiry' 503: description: Service Unavailable. schema: $ref: '#/definitions/ResponseInquiry' 504: description: Gatewaty Timeout. schema: $ref: '#/definitions/ResponseInquiry' operationId: status parameters: - $ref: '#/parameters/Authorization' - $ref: '#/parameters/id' - $ref: '#/parameters/Signature' definitions: Amount: properties: value: type: number format: double example: 5 currency: type: string description: Currency used in the transaction. example: EUR additionalProperties: false description: Parameter with the value and currency of the transaction. required: - value - currency Customer: properties: customerInfo: description: Object that defines the customer predefined information (name, age, etc). Check the CustomerInfo definition. $ref: '#/definitions/CustomerInfo' extendedInfo: type: array items: $ref: '#/definitions/ExtendedInfo' description: Key Value tuple array. additionalProperties: false description: Object that defines a customer. CustomerInfo: properties: customerName: type: string description: Name of the customer. Maximum length is 45. maxLength: 45 example: John customerEmail: type: string description: Customer e-mail example: john@mail.com shippingAddress: $ref: '#/definitions/Address' description: Object that defines the customers address. Check the Address definition. billingAddress: $ref: '#/definitions/Address' description: Object that defines the customers address. Check the Address definition. additionalProperties: false description: Object that defines the predefined customer information. Deviceinfo: properties: browserAcceptHeader: type: string browserJavaEnabled: type: string browserLanguage: type: string browserColorDepth: type: string browserScreenHeight: type: string browserScreenWidth: type: string browserTZ: type: string browserUserAgent: type: string systemFamily: type: string systemVersion: type: string systemArchitecture: type: string deviceManufacturer: type: string deviceModel: type: string deviceID: type: string applicationName: type: string applicationVersion: type: string geoLocalization: type: string ipAddress: type: string additionalProperties: false description: Object that defines the customer device information. ExtendedInfo: type: object properties: key: type: string value: type: string description: Key value tuple. required: - key - value Info: properties: deviceInfo: $ref: '#/definitions/Deviceinfo' description: Object that defines the customers device predefined information. Check the DeviceInfo definition. customerInfo: type: array items: $ref: '#/definitions/ExtendedInfo' description: Key Value tuple array. channelInfo: type: array items: $ref: '#/definitions/ExtendedInfo' description: Key Value tuple array. additionalProperties: false description: Object that defines the transaction additional information OriginalTransaction: properties: id: type: string datetime: type: string recipientId: type: string description: Original Transaction ID additionalProperties: false Merchant: properties: terminalId: type: integer example: "47215" description: Merchant terminal id. format: int32 channel: type: string description: Merchant channel. example: web merchantTransactionId: type: string description: Unique id used by the merchant. example: "5351136" maxLength: 35 additionalProperties: false description: Object that defines a Merchant. RequestCheckout: properties: merchant: description: Object that defines a Merchant. Check the Merchant definition. $ref: '#/definitions/Merchant' customer: description: Object that defines a Customer. Check the Customer definition. $ref: '#/definitions/Customer' transaction: description: Object that defines a Transaction. Check the Transaction definition. $ref: '#/definitions/Transaction' info: $ref: '#/definitions/Info' description: Object that defines the aditional info provided by the merchant. Check the Info definition. originalTransaction: $ref: '#/definitions/OriginalTransaction' description: Original transaction of a Backoffice transaction. tokenisation: $ref: '#/definitions/Tokenisation' description: Field with tokenisation details (see tokenisation Request and paymentTokens). merchantInitiatedTransaction: $ref: '#/definitions/MerchantInitiatedTransactionInput' description: Provided field to create a recurring transaction. validity Date is the date until is possible to perform recurring transactions over the specified transaction. mandate: $ref: '#/definitions/Mandate' description: Object that defines a MBWAY Mandate. additionalProperties: false description: Object that defines the checkout operation request fields TokenisationRequest: properties: tokeniseCard: type: boolean description: Provided field on Checkout request to perform card tokenisation. PaymentTokenItem: type: object properties: tokenType: type: string value: type: string description: Token value tuple. Tokenisation: properties: tokenisationRequest: $ref: '#/definitions/TokenisationRequest' paymentTokens: type: array items: $ref: '#/definitions/PaymentTokenItem' additionalProperties: false description: Customer payment tokens. This tokens are provided at the end of a successful. ResponseInquiry: properties: returnStatus: description: 'Describes the status of the request. (Attention: it doesn''t describe the state of the transaction itself).' $ref: '#/definitions/ReturnStatus' paymentStatus: type: string transactionStatusCode: type: string maxLength: 5 description: 'External Transaction Status Code (ex: EXXXX)' transactionStatusDescription: type: string maxLength: 256 description: Description of External Transaction Status Code paymentMethod: type: string transactionID: type: string amount: description: Object that defines the amount. Check the Amount definition $ref: '#/definitions/Amount' merchant: $ref: '#/definitions/Merchant' description: Object that defines a Merchant. Check the Merchant definition. paymentType: type: string description: Transaction payment type. Purchase or Authorisation. paymentReference: $ref: '#/definitions/PaymentInquiryReference' token: $ref: '#/definitions/TokenInquiry' merchantInitiatedTransaction: description: Object that defines a Recurring Transaction. Check the Recurring Transaction definition. $ref: '#/definitions/MerchantInitiatedTransactionStatusResponse' threeDSecure: $ref: '#/definitions/ThreeDSecureInquiry' execution: description: Object that defines an Execution. See the Execution definition. example: "" $ref: '#/definitions/Execution' additionalProperties: false description: Object that defines the inquiry operation return fields ReturnCheckout: properties: returnStatus: description: Object that defines the Status of the transaction. Check the ReturnStatus definition. example: "" $ref: '#/definitions/ReturnStatus' transactionID: type: string description: Unique identify of the transaction. example: 42f59038f3f14e618d091da8bf3b717e9999 transactionSignature: type: string example: 42f59038f3f14e618d091da8bf3b717e9999 amount: description: Object that defines the amount. Check the Amount definition $ref: '#/definitions/Amount' merchant: description: Object that defines a Merchant. Check the Merchant definition. $ref: '#/definitions/Merchant' paymentMethodList: type: array description: List of payment methods. $ref: '#/definitions/PaymentMethodList' tokenList: type: array description: Payment tokens. items: $ref: '#/definitions/Token' formContext: type: string description: String given by Checkout Response, to be passed to the spg-form (see SIBS Payment Gateway Integration Guide). merchantInitiatedTransaction: description: Object that defines a Merchant Initiated transaction. $ref: '#/definitions/MerchantInitiatedTransactionOutput' mandate: description: Object that defines a MBWAY Mandate. properties: mandateAvailable: type: boolean description: MB WAY Mandate Available for use. Is set to true if current Client has an active mandate for current Merchant. termsAndConditions: type: string description: Merchant URI with Authorized Payment Terms & Conditions. expiry: type: string format: date-time description: Expiration datetime. execution: description: Object that defines an Execution. See the Execution definition. example: "" $ref: '#/definitions/Execution' additionalProperties: false description: Object that defines the checkout operation return fields ReturnStatus: properties: statusCode: type: string description: Identifier code of the processed transaction status. example: "000" statusMsg: type: string description: Message of the processed transaction status. example: Success statusDescription: type: string description: Description of the processed transaction status. additionalProperties: false description: Object that defines the status of the processed transaction. required: - statusCode - statusDescription Transaction: properties: transactionTimestamp: type: string format: date-time description: Timestamp of the transaction. example: "2020-12-10T15:41:56.971Z" description: type: string description: Transaction description. example: Transaction short description moto: type: boolean description: Mail Order / Telephone Order example: false paymentType: type: string enum: - AUTH - PURS - CAPT - CAUT - RFND - RCON - RVSL - STIQ - PREF - CPRF - CMBW default: AUTH description: Type of payment used by the client. paymentMethod: description: Method of payment used by the client. example: "" $ref: '#/definitions/PaymentMethodList' amount: example: "" description: Object that defines the amount. Check the Amount definition. $ref: '#/definitions/Amount' paymentReference: description: Payment reference details in case of customer select payment reference (Multibanco) payment method. $ref: '#/definitions/PaymentReference' threeDSecureOptions: description: 3D Secure Requested Options $ref: '#/definitions/ThreeDSecureOptions' subMerchant: description: This complex type has the submerchant info. \n This attributes will be mandatory in case the Merchant is a Payment Facilitator. $ref: '#/definitions/SubMerchantRequest' additionalProperties: false description: Object that defines a transaction. ThreeDSecureOptions: properties: authenticationExemption: type: string description: Requested Authentication Exemption Type. Possible values are { "WHITELIST_PROMPT" - Whitelist Exemption Cardholder Prompt, "WHITELIST" - Whitelist Exemption, "LOW_VALUE" - Low Value Amount Exemption, "LOW_RISK"-Low Risk Exemption, "NONE"- None}. enum: - LOW_VALUE - LOW_RISK - NONE - WHITELIST_PROMPT - WHITELIST required: - authenticationExemption Address: properties: street1: type: string description: Address Street. Maximum length is 50. example: First street street2: type: string description: Address Additional Street. Maximum length is 19. city: type: string description: Address city or town. Maximum length is 35. example: Lisbon postcode: type: string description: Address Postal Code. Maximum length is 16. example: 1700-123 country: type: string description: Country Code. Alpha2 example: PT countrySubDivision: type: string description: Address Country Sub Division. Maximum length is 35. maxLength: 35 additionalProperties: true Mandate: properties: mandateId: type: string description: MBWAY Mandate Identifier. Not applicable in creation. Mandatory in further usage. pattern: ^[a-zA-Z0-9]+ default: "9999999999999999999999999999999999999999999999999999999999999999" mandateType: type: string description: Mandate Type. \n Possible values are ("ONECLIK", "SUBSCRIPTION"). Mandatory in creation. Not applicable in further usage. enum: - ONECLICK - SUBSCRIPTION default: ONECLICK mandateCreationOnly: type: boolean description: Possible values are ("True"- Only Creates Mandate, "False" - Creates Mandate and requests payment). Mandatory in creation. Not applicable in further usage. (Reserved for Future Use) disableMandateMBWAYFallback: type: boolean description: 'Possible Values: \n "false" - If mandate limits are exceeded and do not allow mandate usage, an MBWAY Purchase is performed. \n "true" - If mandate limits are exceeded and do not allow mandate usage, payment ends without success. \n Not applicable in creation. Optional for Payment with MB WAY Mandate. In this last case, if not present the "false" value is assumed.' additionalProperties: true PaymentReference: properties: entity: type: string description: Entity used in Payment Reference example: "25100" minAmount: description: Minimum amount of the transaction. $ref: '#/definitions/Amount' maxAmount: description: Maximum amount of the transaction. $ref: '#/definitions/Amount' initialDatetime: type: string format: date-time example: "2020-05-20T15:41:56.971Z" description: Date from when the payment reference is valid (if generated). finalDatetime: type: string format: date-time example: "2020-12-31T15:41:56.971Z" description: Payment reference expiring date (if generated). paymentEntityDescription: type: string minLength: 1 maxLength: 40 description: Payment Entity Reference Description. additionalProperties: false PaymentInquiryReference: properties: reference: type: string description: Payment Reference entity: type: string description: Entity used in Payment Reference paymentEntity: type: string description: Payment Reference Entity amount: description: Object that defines the amount. Check the Amount definition. $ref: '#/definitions/Amount' status: type: string description: Payment Reference Status enum: - UNPAID - PAID - PARTPAIDCLS - PARTPAIDOPN - CANC - UNKN default: PAID expireDate: type: string description: Expiration Date of the Reference format: date-time additionalProperties: false SubMerchantRequest: properties: tin: type: string pattern: ^\d{1,20}$ minLength: 1 maxLength: 20 description: SubMerchant Tax Identification Numeric name: type: string minLength: 1 maxLength: 50 description: SubMerchant Name mcc: type: number minimum: 0 maximum: 9999 description: Merchant Category Code sic: type: number minimum: 0 maximum: 99999 description: Standard Industrial Classification (SIC) / Código de Atividade Económica (CAE) additionalProperties: false Token: properties: tokenName: type: string tokenType: type: string enum: - Email - MobilePhone - QRCodeMBWAY1 - Card default: Card value: type: string maskedPAN: type: string expireDate: type: string example: PT additionalProperties: false TokenInquiry: properties: tokenName: type: string tokenType: type: string enum: - Email - MobilePhone - QRCodeMBWAY1 - Card default: Card value: type: string maskedPAN: type: string expireDate: type: string example: PT additionalProperties: false ThreeDSecureInquiry: properties: whitelistStatus: description: 'Possible values are: \n • Y = 3DS Requestor is whitelisted by cardholder \n • N = 3DS Requestor is not whitelisted by cardholder \n • E = Not eligible as determined by issuer \n • P = Pending confirmation by cardholder \n • R = Cardholder rejected \n • U = Whitelist status unknown, unavailable, or does not apply.' type: string enum: - "Y" - "N" - E - P - R - U required: - whitelistStatus Execution: properties: startTime: type: string description: Time of the acceptance of the request by the API. format: date-time example: "2020-07-15T12:10:49.131+01:00" endTime: type: string description: Time of the response to the request by the API. format: date-time example: "2020-07-15T12:10:49.131+01:00" additionalProperties: false description: Object that encapsulates technical execution information. required: - startTime - endTime MerchantInitiatedTransactionOutput: properties: termsAndConditions: type: string description: Merchant URI with Merchant Initiated Transactions Terms & Conditions. additionalProperties: false required: - termsAndConditions MerchantInitiatedTransactionStatusResponse: properties: status: type: string description: Recurring Transaction Outcome. \n Possible values are "Success", "Decline", "Error". additionalProperties: false MerchantInitiatedTransactionInput: properties: type: type: string description: Merchant Initiated Transaction Type. \n Possible values are "UCOF"-"Unscheduled Credential on File" and "RCRR"-"Recurring". enum: - UCOF - RCRR default: RCRR validityDate: type: string description: Expiration Date of Merchant Initiated Transaction. format: date-time example: "2020-07-15T12:10:49.131+01:00" amountQualifier: type: string description: Qualifies the amount associated with the Merchant Initiated Transaction. Possible values are "ACTUAL"-"Actual amount", "ESTIMATED"-"Estimated amount (the final amount could be above or below)" and "DEFAULT"-"Default amount". If not present, the "DEFAULT" value is assumed. If merchantInitiatedTransaction has MITType "UCOF", the amountQualifier must be set to "ESTIMATED". enum: - DEFAULT - ESTIMATED - ACTUAL default: ESTIMATED description: type: string description: Description of the Merchant Initiated Transaction. example: Merchant Initiated Transaction schedule: $ref: '#/definitions/Schedule' description: Merchant Initiated Transaction Schedule active: type: boolean description: Merchant Initiated Transaction Status. additionalProperties: false description: Object that defines a Merchant Initiated transaction request. required: - type Schedule: properties: initialDate: type: string format: date-time example: "2020-07-15T12:10:49.131+01:00" finalDate: type: string format: date-time example: "2020-07-15T12:10:49.131+01:00" interval: type: string enum: - DAILY - WEEKLY - BIWEEKLY - MONTHLY - QUARTERLY - SEMIANNUAL - ANNUAL default: DAILY additionalProperties: false PaymentMethodList: type: array items: type: string enum: - CARD - MBWAY - QRCODE - REFERENCE - TOKEN - MANDATE - XPAY description: Method of payment used by the client. tags: [] security: - clientid: [] parameters: Authorization: name: Authorization type: string required: true in: header Signature: name: Signature type: string description: For now, the type of HMAC used will be SHA2 (SHA512). base64 required: false in: header maxLength: 128 id: name: id type: string required: true in: path merchantTransactionId: name: merchantTransactionId type: string required: false in: query maxLength: 35 x-ibm-endpoints: - endpointUrl: https://sandbox.sibspayments.com type: - production - development ...