> For the complete documentation index, see [llms.txt](https://docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verifone.com/api-reference/open-api-references/ecommerce/alternative-payment-methods.md). # Alternative Payment Methods The APM endpoints follow a two-step pattern: **Initiate** creates the transaction and returns a redirect URL or client token, then the cardholder completes the flow externally. A second **Complete** call may be required to finalise the order. ## Klarna Klarna uses a two-step flow: initiate returns a `client_token` for the Klarna SDK; once the shopper completes checkout, call the complete endpoint with the `authorization_token`. {% stepper %} {% step %} #### Initiate Klarna Payment {% endstep %} {% step %} #### Complete Klarna Payment {% endstep %} {% endstepper %} ### Key Differences Between Steps {% columns %} {% column %} #### Step 1 — Initiate * `entity_id` ✅ Required * `line_items` ✅ Required * `locale` ✅ Required * Returns `client_token` for Klarna SDK * Returns `payment_method_categories` {% endcolumn %} {% column %} #### Step 2 — Complete * `id` from Step 1 in path ✅ Required * `authorization_token` from Klarna SDK * Returns `authorized_payment_method` with `payment_type` and instalment details {% endcolumn %} {% endcolumns %} ## Affirm Affirm also requires a two-step flow. Initiation returns either a `payment_url` (REDIRECT mode) or a `checkout_id` and `public_api_key` (MODAL mode). {% stepper %} {% step %} #### Initiate Affirm Payment {% endstep %} {% step %} #### Complete Affirm Payment {% endstep %} {% endstepper %} {% hint style="warning" %} `x-vfi-api-idempotencykey` is **required** for both Affirm initiation and completion requests. It is also required when processing a refund for an Affirm payment. {% endhint %} ## Vipps Vipps initiates and returns a `redirect_url` to which the cardholder is redirected to authenticate. No separate completion step is required — Vipps notifies Verifone of the outcome asynchronously. ## Initiate a Vipps payment > Initiate a Vipps payment. ```json {"openapi":"3.0.0","info":{"title":"Verifone eCommerce API","version":"2.38.1"},"servers":[{"url":"https://emea.gsc.verifone.cloud/oidc","description":"EMEA Production"},{"url":"https://us.gsc.verifone.cloud/oidc","description":"Americas Production"},{"url":"https://nz.gsc.verifone.cloud/oidc","description":"New Zealand Production"},{"url":"https://cst.test-gsc.vfims.com/oidc","description":"Global Sandbox"},{"url":"https://uscst-gb.gsc.vficloud.net/oidc","description":"Americas Sandbox"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"vippsPaymentInitiationRequest":{"title":"Vipps Payment Initiation Request","required":["amount","currency_code","customer","merchant_reference","payment_provider_contract","redirect_url"],"type":"object","properties":{"payment_provider_contract":{"type":"string","description":"The identifier of payment provider contract you want to process the transaction request with.","format":"uuid-flexible"},"threed_secure":{"$ref":"#/components/schemas/ThreeDSecure"},"app_phone_number":{"maxLength":18,"type":"string","description":"The Phone Number registered with Vipps Mobile APP."},"redirect_url":{"maxLength":2048,"type":"string","description":"Checkout Redirect URL which will be used by Vipps on Payment Completion."},"is_app":{"type":"boolean","description":"Flag to identify the transaction originated from APP or Browser.","default":false},"amount":{"type":"integer","description":"Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field."},"auth_type":{"type":"string","description":"Flags a payment request for either pre-authorization or final authorization.\n * `PRE_AUTH` is used when the authorized amount is unknown and can be adjusted later.\n * `FINAL_AUTH` is used when a final authorized amount is known and the transaction will definitely be captured in whole.","enum":["PRE_AUTH","FINAL_AUTH"],"default":"FINAL_AUTH"},"capture_now":{"type":"boolean","description":"Whether auto-capture or not. Setting the value to 'false' will only authorize the transaction.","default":true},"customer":{"type":"string","description":"The ID of a customer.","format":"uuid-flexible","title":"Customer ID"},"customer_ip":{"description":"The IP Address of the customer where the transaction was initiated.","maxLength":15,"oneOf":[{"type":"string","format":"ipv4"},{"type":"string","format":"ipv6"}]},"dynamic_descriptor":{"maxLength":25,"type":"string","description":"A short [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) to be shown on bank statement of the customer. Please refer to the integration guide for the format requirements."},"merchant_reference":{"type":"string","description":"A reference specified by the merchant to identify the transaction.","maxLength":50},"shipping_information":{"allOf":[{"$ref":"#/components/schemas/ShippingInformationDto"}]},"user_agent":{"type":"string","description":"The full user agent string of the device the customer used to submit the transaction.","maxLength":256},"sales_description":{"type":"string","description":"A reference used by the merchant to typically capture a description of the service provided. It could then be used by the merchant to help locate transactions. One could envision a situation where a merchant is trying to locate a transaction/ receipt but in speaking with the customer, the only (or at least a predominant) detail is what service was rendered","maxLength":200},"currency_code":{"title":"Currency Code","type":"string","description":"Three-letter ISO 4217 alphabetical currency code. e.g. USD. Values correspond\nto [ISO 4217](https://wikipedia.org/wiki/ISO_4217).\n\nPlease note that Klarna only supports Norwegian krone (NOK).","enum":["NOK"]},"sca_compliance_level":{"type":"string","description":" * `NONE`: No SCA required.\n * `WALLET`: Depend on the wallet SCA mechanism. For Google Pay this means that MasterCard will shift liability, Visa will not.\n * `FORCE_3DS`: Do an additional 3DS step regardless of whether the wallet indicates the token is SCA-compliant.","enum":["NONE","WALLET","FORCE_3DS"],"default":"WALLET"},"sca_exemption":{"type":"string","description":"Use this field to request your transaction to be exempted from the application of the Strong Customer Authentication (SCA). Be advised that the use of this field may result to your liability in case of fraudulent transaction.\n Possible Values:\n 1 - Low value payment\n 2 - Acquirer Transaction Risk Analysis\n 3 - Trusted beneficiary exemption\n 4 - Secure Corporate Payment (SCP) exemption\n 5 - Merchant Initiated Transaction\n 6 - SCA Delegation.\n\n**NOTE:** This only applies when `sca_compliance_level` = `NONE`","enum":["1","2","3","4","5","6"]}}},"ThreeDSecure":{"type":"object","properties":{"eci_flag":{"type":"string","title":"Electronic Commerce Indicator.","enum":["00","01","02","03","04","05","06","07"]},"enrolled":{"type":"string","title":"The enrolment response status of Authentication eligibility from the Directory Server.","description":"Possible Values:\n Y - Yes, Bank is participating in 3-D Secure protocol and will return the ACSUrl.\n N - No, Bank is not participating in 3-D Secure protocol.\n U - Unavailable, the DS or ACS is not available for authentication at the time of the request.\n B - Bypass, merchant authentication rule is triggered to bypass authentication in this use case.\n NOTE: If the Enrolled value is NOT Y, then the Consumer is NOT eligible for Authentication."},"cavv":{"type":"string","maxLength":48,"title":"Cardholder Authentication Verification Value (CAVV)","description":"Base64-encoded values of 28 or 32 characters. Hex-encoded values of 40 or 48 characters."},"cavv_algorithm":{"type":"string","description":"Indicates the algorithm used to generate the CAVV value.Please refer to the integration guide for information on its usage."},"pares_status":{"type":"string","title":"Authentication response code.","description":"Possible Values:\n Y - Successful Authentication.\n U - Unable to Complete Authentication\n A - Successful Attempts Transaction."},"xid":{"type":"string","description":"Transaction identifier resulting from authentication processing.Please refer to the integration guide for information on its usage."},"ds_transaction_id":{"type":"string","title":"The unique transaction identifier","description":"The unique transaction identifier assigned by the Directory Server. Supported for 3D Secure v2 only."},"threeds_version":{"type":"string","title":"The 3DS version used to process the transaction.","enum":["1.0.2","2.1.0","2.2.0"]}}},"ShippingInformationDto":{"type":"object","additionalProperties":false,"description":"The address where the purchased goods should be delivered to.","title":"Shipping Address","properties":{"address":{"type":"string","maxLength":300,"description":"Street address of the recipient."},"city":{"type":"string","maxLength":28,"description":"City of the recipient."},"country":{"type":"string","maxLength":2,"minLength":2,"format":"country-code","description":"A 2-letter ISO3166 alpha-2 country code for the address."},"postal_code":{"type":"string","minLength":1,"maxLength":16,"description":"A postal code for the address."},"email":{"type":"string","title":"Email Address","minLength":3,"maxLength":254,"format":"email","description":"A valid internationalized email address, as defined by RFC 5322, RFC 6530, and other RFCs. Due to RFC 5321, an email address can be up to 254 characters long even though up to 64 characters are allowed before and 255 characters are allowed after the @ sign. This pattern verifies only that the string contains an unquoted @ sign. See https://tools.ietf.org/html/rfc5322#section-3.4.1."},"first_name":{"type":"string","maxLength":100,"description":"First name of the recipient."},"last_name":{"type":"string","maxLength":100,"description":"Last name of the recipient."},"phone":{"type":"number","maxLength":15,"description":"Numbers only, no dash or any other separator."},"state":{"type":"string","maxLength":35,"description":"A region / state / province for the address."}},"required":["address","city","country","postal_code"]},"vippsPaymentInitiationResponse":{"title":"Vipps Payment Initiation Response","type":"object","properties":{"id":{"title":"Transaction ID","type":"string","description":"The ID of the transaction.","format":"uuid-flexible"},"redirect_url":{"type":"string","description":"Vipps Host Redirection URL."},"amount":{"type":"integer","description":"Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field."},"blocked":{"type":"boolean","description":"True if the transaction has been blocked by a ruleset, false otherwise"},"created_at":{"type":"string","description":"The time at which the transaction was created.","format":"date-time"},"customer":{"type":"string","description":"The ID of a customer"},"details":{"$ref":"#/components/schemas/ecomPaymentResponse_details"},"merchant_reference":{"type":"string","description":"A reference specified by the merchant to identify the transaction.","maxLength":50},"processor":{"type":"string","description":"The name of the processor used for this transaction","default":"NETS"},"payment_product":{"type":"string","description":"The payment product corresponding to this transaction","default":"CARD"},"payment_product_type":{"$ref":"#/components/schemas/PaymentProductType"},"shipping_information":{"allOf":[{"$ref":"#/components/schemas/ShippingInformationDto"}]},"status":{"type":"string","description":"The outcome of the payment request.","title":"Ecommerce Transaction Status","enum":["INITIATED","AUTHORIZED","AUTHORIZATION_VOIDED","CANCELLED","CUSTOMER_ACCEPTED","REFUNDED","FAILED","PENDING","DECLINED","SETTLEMENT_CANCELLED","SETTLEMENT_REQUESTED","SETTLEMENT_SUBMITTED","SETTLEMENT_COMPLETED","SETTLEMENT_PARTIAL","SETTLEMENT_DECLINED","VOIDED","UNKNOWN"]},"status_reason":{"type":"string","description":"Message provided by the 3rd party service as additional information, when the transaction does not succeed."},"created_by":{"type":"string","description":"The ID of the user who initiated the transaction. Only set when shopper_interaction = moto, mail_order or telephone_order"},"shopper_interaction":{"type":"string","description":"Determines the sales channel the shopper gives their card details through:\n\n * `ECOMMERCE` Online transactions where the cardholder is present.\n\n * `MAIL` order transactions where the shopper is in contact with the merchant via email.\n\n * `TELEPHONE` order transactions where the shopper is in contact with the merchant via telephone.","enum":["ECOMMERCE","MAIL","TELEPHONE"],"default":"ECOMMERCE"},"geo_location":{"type":"array","description":"The latitude / longitude resolved from the customer's ip address.","items":{"type":"number"}},"city":{"type":"string","description":"The city resolved from the customer's ip address."},"country_code":{"title":"Country Code","type":"string","description":"The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.
Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.
."}}},"ecomPaymentResponse_details":{"type":"object","properties":{"auto_capture":{"type":"boolean","description":"Indicates whether the transaction would be automatically captured upon authorisation."},"mid":{"type":"string","description":"Merchant ID (MID)","format":"integer"}}},"PaymentProductType":{"title":"Payment Product Type","type":"string","description":"The payment product type corresponding to this transaction. Fees applied to the transaction, is based on the payment product","enum":["Affirm","Amex","Crypto","Diners Club International","Discover","JCB","Klarna","Maestro","Mastercard","OP Online Payment","Swish","Unknown","Visa"],"default":"Unknown"},"BadRequestV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[400],"default":400},"message":{"type":"string","enum":["At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."],"default":"At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."}},"required":["message"]},"UnauthorizedV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[401],"default":401},"message":{"type":"string","enum":["Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."],"default":"Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."}},"required":["message"]},"ForbiddenV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[403],"default":403},"message":{"type":"string","enum":["Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."],"default":"Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."}},"required":["message"]},"NotFoundV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[404],"default":404},"message":{"type":"string","enum":["The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."],"default":"The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."}},"required":["message"]},"InternalErrorV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[500],"default":500},"message":{"type":"string","enum":["Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"],"default":"Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"}},"required":["message"]}}},"paths":{"/api/v2/transactions/vipps":{"post":{"tags":["Ecom Payments"],"summary":"Initiate a Vipps payment","description":"Initiate a Vipps payment.","operationId":"vippsTransaction","parameters":[{"name":"x-vfi-api-idempotencykey","required":false,"in":"header","schema":{"type":"string","description":"A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/vippsPaymentInitiationRequest"}}}},"responses":{"201":{"description":"The Vipps Payment Initiation Response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/vippsPaymentInitiationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestV2Docs"}}}},"401":{"description":"Unauthorised Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedV2Docs"}}}},"403":{"description":"Forbidden Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenV2Docs"}}}},"404":{"description":"Not Found Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundV2Docs"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorV2Docs"}}}}}}}}} ``` ## MobilePay MobilePay follows the same redirect pattern as Vipps. ## Initiate a MobilePay payment > Initiate a MobilePay payment. ```json {"openapi":"3.0.0","info":{"title":"Verifone eCommerce API","version":"2.38.1"},"servers":[{"url":"https://emea.gsc.verifone.cloud/oidc","description":"EMEA Production"},{"url":"https://us.gsc.verifone.cloud/oidc","description":"Americas Production"},{"url":"https://nz.gsc.verifone.cloud/oidc","description":"New Zealand Production"},{"url":"https://cst.test-gsc.vfims.com/oidc","description":"Global Sandbox"},{"url":"https://uscst-gb.gsc.vficloud.net/oidc","description":"Americas Sandbox"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"mobilePayPaymentInitiationRequest":{"title":"MobilePay Payment Initiation Request","required":["amount","currency_code","customer","merchant_reference","payment_provider_contract","redirect_url"],"type":"object","properties":{"payment_provider_contract":{"type":"string","description":"The identifier of payment provider contract you want to process the transaction request with.","format":"uuid-flexible"},"threed_secure":{"$ref":"#/components/schemas/ThreeDSecure"},"redirect_url":{"maxLength":2048,"type":"string","description":"Checkout Redirect URL which will be used by MobilePay on Payment Completion."},"amount":{"type":"integer","description":"Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field."},"auth_type":{"type":"string","description":"Flags a payment request for either pre-authorization or final authorization.\n * `PRE_AUTH` is used when the authorized amount is unknown and can be adjusted later.\n * `FINAL_AUTH` is used when a final authorized amount is known and the transaction will definitely be captured in whole.","enum":["PRE_AUTH","FINAL_AUTH"],"default":"FINAL_AUTH"},"capture_now":{"type":"boolean","description":"Whether auto-capture or not. Setting the value to 'false' will only authorize the transaction.","default":true},"customer":{"type":"string","description":"The ID of a customer.","format":"uuid-flexible","title":"Customer ID"},"customer_ip":{"description":"The IP Address of the customer where the transaction was initiated.","maxLength":15,"oneOf":[{"type":"string","format":"ipv4"},{"type":"string","format":"ipv6"}]},"dynamic_descriptor":{"maxLength":25,"type":"string","description":"A short [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) to be shown on bank statement of the customer. Please refer to the integration guide for the format requirements."},"merchant_reference":{"type":"string","description":"A reference specified by the merchant to identify the transaction.","maxLength":50},"shipping_information":{"allOf":[{"$ref":"#/components/schemas/ShippingInformationDto"}]},"user_agent":{"type":"string","description":"The full user agent string of the device the customer used to submit the transaction.","maxLength":256},"sales_description":{"type":"string","description":"A reference used by the merchant to typically capture a description of the service provided. It could then be used by the merchant to help locate transactions. One could envision a situation where a merchant is trying to locate a transaction/ receipt but in speaking with the customer, the only (or at least a predominant) detail is what service was rendered","maxLength":200},"currency_code":{"title":"Currency Code","type":"string","description":"Three-letter ISO 4217 alphabetical currency code. e.g. USD. Values correspond\nto [ISO 4217](https://wikipedia.org/wiki/ISO_4217).\n\nPlease note that Klarna only supports EURO (EUR) and Danish krone (DKK).","enum":["EUR","DKK"]},"sca_compliance_level":{"type":"string","description":" * `NONE`: No SCA required.\n * `WALLET`: Depend on the wallet SCA mechanism. For Google Pay this means that MasterCard will shift liability, Visa will not.\n * `FORCE_3DS`: Do an additional 3DS step regardless of whether the wallet indicates the token is SCA-compliant.","enum":["NONE","WALLET","FORCE_3DS"],"default":"WALLET"},"sca_exemption":{"type":"string","description":"Use this field to request your transaction to be exempted from the application of the Strong Customer Authentication (SCA). Be advised that the use of this field may result to your liability in case of fraudulent transaction.\n Possible Values:\n 1 - Low value payment\n 2 - Acquirer Transaction Risk Analysis\n 3 - Trusted beneficiary exemption\n 4 - Secure Corporate Payment (SCP) exemption\n 5 - Merchant Initiated Transaction\n 6 - SCA Delegation.\n\n**NOTE:** This only applies when `sca_compliance_level` = `NONE`","enum":["1","2","3","4","5","6"]}}},"ThreeDSecure":{"type":"object","properties":{"eci_flag":{"type":"string","title":"Electronic Commerce Indicator.","enum":["00","01","02","03","04","05","06","07"]},"enrolled":{"type":"string","title":"The enrolment response status of Authentication eligibility from the Directory Server.","description":"Possible Values:\n Y - Yes, Bank is participating in 3-D Secure protocol and will return the ACSUrl.\n N - No, Bank is not participating in 3-D Secure protocol.\n U - Unavailable, the DS or ACS is not available for authentication at the time of the request.\n B - Bypass, merchant authentication rule is triggered to bypass authentication in this use case.\n NOTE: If the Enrolled value is NOT Y, then the Consumer is NOT eligible for Authentication."},"cavv":{"type":"string","maxLength":48,"title":"Cardholder Authentication Verification Value (CAVV)","description":"Base64-encoded values of 28 or 32 characters. Hex-encoded values of 40 or 48 characters."},"cavv_algorithm":{"type":"string","description":"Indicates the algorithm used to generate the CAVV value.Please refer to the integration guide for information on its usage."},"pares_status":{"type":"string","title":"Authentication response code.","description":"Possible Values:\n Y - Successful Authentication.\n U - Unable to Complete Authentication\n A - Successful Attempts Transaction."},"xid":{"type":"string","description":"Transaction identifier resulting from authentication processing.Please refer to the integration guide for information on its usage."},"ds_transaction_id":{"type":"string","title":"The unique transaction identifier","description":"The unique transaction identifier assigned by the Directory Server. Supported for 3D Secure v2 only."},"threeds_version":{"type":"string","title":"The 3DS version used to process the transaction.","enum":["1.0.2","2.1.0","2.2.0"]}}},"ShippingInformationDto":{"type":"object","additionalProperties":false,"description":"The address where the purchased goods should be delivered to.","title":"Shipping Address","properties":{"address":{"type":"string","maxLength":300,"description":"Street address of the recipient."},"city":{"type":"string","maxLength":28,"description":"City of the recipient."},"country":{"type":"string","maxLength":2,"minLength":2,"format":"country-code","description":"A 2-letter ISO3166 alpha-2 country code for the address."},"postal_code":{"type":"string","minLength":1,"maxLength":16,"description":"A postal code for the address."},"email":{"type":"string","title":"Email Address","minLength":3,"maxLength":254,"format":"email","description":"A valid internationalized email address, as defined by RFC 5322, RFC 6530, and other RFCs. Due to RFC 5321, an email address can be up to 254 characters long even though up to 64 characters are allowed before and 255 characters are allowed after the @ sign. This pattern verifies only that the string contains an unquoted @ sign. See https://tools.ietf.org/html/rfc5322#section-3.4.1."},"first_name":{"type":"string","maxLength":100,"description":"First name of the recipient."},"last_name":{"type":"string","maxLength":100,"description":"Last name of the recipient."},"phone":{"type":"number","maxLength":15,"description":"Numbers only, no dash or any other separator."},"state":{"type":"string","maxLength":35,"description":"A region / state / province for the address."}},"required":["address","city","country","postal_code"]},"mobilePayPaymentInitiationResponse":{"title":"MobilePay Payment Initiation Response","type":"object","properties":{"id":{"title":"Transaction ID","type":"string","description":"The ID of the transaction.","format":"uuid-flexible"},"redirect_url":{"type":"string","description":"MobilePay Host Redirection URL."},"amount":{"type":"integer","description":"Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field."},"blocked":{"type":"boolean","description":"True if the transaction has been blocked by a ruleset, false otherwise"},"created_at":{"type":"string","description":"The time at which the transaction was created.","format":"date-time"},"customer":{"type":"string","description":"The ID of a customer"},"details":{"$ref":"#/components/schemas/ecomPaymentResponse_details"},"merchant_reference":{"type":"string","description":"A reference specified by the merchant to identify the transaction.","maxLength":50},"processor":{"type":"string","description":"The name of the processor used for this transaction","default":"NETS"},"payment_product":{"type":"string","description":"The payment product corresponding to this transaction","default":"CARD"},"payment_product_type":{"$ref":"#/components/schemas/PaymentProductType"},"shipping_information":{"allOf":[{"$ref":"#/components/schemas/ShippingInformationDto"}]},"status":{"type":"string","description":"The outcome of the payment request.","title":"Ecommerce Transaction Status","enum":["INITIATED","AUTHORIZED","AUTHORIZATION_VOIDED","CANCELLED","CUSTOMER_ACCEPTED","REFUNDED","FAILED","PENDING","DECLINED","SETTLEMENT_CANCELLED","SETTLEMENT_REQUESTED","SETTLEMENT_SUBMITTED","SETTLEMENT_COMPLETED","SETTLEMENT_PARTIAL","SETTLEMENT_DECLINED","VOIDED","UNKNOWN"]},"status_reason":{"type":"string","description":"Message provided by the 3rd party service as additional information, when the transaction does not succeed."},"created_by":{"type":"string","description":"The ID of the user who initiated the transaction. Only set when shopper_interaction = moto, mail_order or telephone_order"},"shopper_interaction":{"type":"string","description":"Determines the sales channel the shopper gives their card details through:\n\n * `ECOMMERCE` Online transactions where the cardholder is present.\n\n * `MAIL` order transactions where the shopper is in contact with the merchant via email.\n\n * `TELEPHONE` order transactions where the shopper is in contact with the merchant via telephone.","enum":["ECOMMERCE","MAIL","TELEPHONE"],"default":"ECOMMERCE"},"geo_location":{"type":"array","description":"The latitude / longitude resolved from the customer's ip address.","items":{"type":"number"}},"city":{"type":"string","description":"The city resolved from the customer's ip address."},"country_code":{"title":"Country Code","type":"string","description":"The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.
Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.
."}}},"ecomPaymentResponse_details":{"type":"object","properties":{"auto_capture":{"type":"boolean","description":"Indicates whether the transaction would be automatically captured upon authorisation."},"mid":{"type":"string","description":"Merchant ID (MID)","format":"integer"}}},"PaymentProductType":{"title":"Payment Product Type","type":"string","description":"The payment product type corresponding to this transaction. Fees applied to the transaction, is based on the payment product","enum":["Affirm","Amex","Crypto","Diners Club International","Discover","JCB","Klarna","Maestro","Mastercard","OP Online Payment","Swish","Unknown","Visa"],"default":"Unknown"},"BadRequestV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[400],"default":400},"message":{"type":"string","enum":["At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."],"default":"At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."}},"required":["message"]},"UnauthorizedV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[401],"default":401},"message":{"type":"string","enum":["Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."],"default":"Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."}},"required":["message"]},"ForbiddenV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[403],"default":403},"message":{"type":"string","enum":["Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."],"default":"Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."}},"required":["message"]},"NotFoundV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[404],"default":404},"message":{"type":"string","enum":["The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."],"default":"The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."}},"required":["message"]},"InternalErrorV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[500],"default":500},"message":{"type":"string","enum":["Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"],"default":"Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"}},"required":["message"]}}},"paths":{"/api/v2/transactions/mobilepay":{"post":{"tags":["Ecom Payments"],"summary":"Initiate a MobilePay payment","description":"Initiate a MobilePay payment.","operationId":"mobilePayTransaction","parameters":[{"name":"x-vfi-api-idempotencykey","required":false,"in":"header","schema":{"type":"string","description":"A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mobilePayPaymentInitiationRequest"}}}},"responses":{"201":{"description":"The MobilePay Payment Initiation Response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mobilePayPaymentInitiationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestV2Docs"}}}},"401":{"description":"Unauthorised Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedV2Docs"}}}},"403":{"description":"Forbidden Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenV2Docs"}}}},"404":{"description":"Not Found Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundV2Docs"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorV2Docs"}}}}}}}}} ``` ## Swish Swish supports both **e-commerce** (redirect) and **m-commerce** (in-app token) flows. For the m-commerce flow, omit `app_phone_number` — the response includes `payment_request_token` to open the Swish app directly. ## Initiate a Swish payment > Initiate a Swish payment. ```json {"openapi":"3.0.0","info":{"title":"Verifone eCommerce API","version":"2.38.1"},"servers":[{"url":"https://emea.gsc.verifone.cloud/oidc","description":"EMEA Production"},{"url":"https://us.gsc.verifone.cloud/oidc","description":"Americas Production"},{"url":"https://nz.gsc.verifone.cloud/oidc","description":"New Zealand Production"},{"url":"https://cst.test-gsc.vfims.com/oidc","description":"Global Sandbox"},{"url":"https://uscst-gb.gsc.vficloud.net/oidc","description":"Americas Sandbox"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"swishPaymentInitiationRequest":{"title":"Swish Payment Initiation Request","required":["amount","currency_code","merchant_reference","payment_provider_contract"],"type":"object","properties":{"entity_id":{"type":"string","description":"The identifier of merchant entity you want to process the transaction request with. Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)","format":"uuid-flexible"},"app_phone_number":{"maxLength":18,"type":"string","description":"The Phone Number registered with Swish Mobile APP. This field is required for ECommerce flow, not needed MCommerce flow."},"amount":{"type":"integer","description":"Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field."},"customer":{"type":"string","description":"The ID of a customer.","format":"uuid-flexible","title":"Customer ID"},"customer_ip":{"description":"The IP Address of the customer where the transaction was initiated.","maxLength":15,"oneOf":[{"type":"string","format":"ipv4"},{"type":"string","format":"ipv6"}]},"dynamic_descriptor":{"type":"string","description":"A short [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) to be shown on bank statement of the customer and also shown in the Swish application. Max 50 chars, allowed characters are the letters a-ö, A-Ö, the numbers 0-9 and the special characters :;.,?!()” and space","maxLength":50},"merchant_reference":{"type":"string","description":"A reference specified by the merchant to identify the transaction.","maxLength":50},"shipping_information":{"allOf":[{"$ref":"#/components/schemas/ShippingInformationDto"}]},"user_agent":{"type":"string","description":"The full user agent string of the device the customer used to submit the transaction.","maxLength":256},"sales_description":{"type":"string","description":"A reference used by the merchant to typically capture a description of the service provided. It could then be used by the merchant to help locate transactions. One could envision a situation where a merchant is trying to locate a transaction/ receipt but in speaking with the customer, the only (or at least a predominant) detail is what service was rendered","maxLength":200},"currency_code":{"title":"Currency Code","type":"string","description":"Three-letter ISO 4217 alphabetical currency code. e.g. USD. Values correspond\nto [ISO 4217](https://wikipedia.org/wiki/ISO_4217).\n\nPlease note that Swish only supports Swedish krona (SEK).","enum":["SEK"]}}},"ShippingInformationDto":{"type":"object","additionalProperties":false,"description":"The address where the purchased goods should be delivered to.","title":"Shipping Address","properties":{"address":{"type":"string","maxLength":300,"description":"Street address of the recipient."},"city":{"type":"string","maxLength":28,"description":"City of the recipient."},"country":{"type":"string","maxLength":2,"minLength":2,"format":"country-code","description":"A 2-letter ISO3166 alpha-2 country code for the address."},"postal_code":{"type":"string","minLength":1,"maxLength":16,"description":"A postal code for the address."},"email":{"type":"string","title":"Email Address","minLength":3,"maxLength":254,"format":"email","description":"A valid internationalized email address, as defined by RFC 5322, RFC 6530, and other RFCs. Due to RFC 5321, an email address can be up to 254 characters long even though up to 64 characters are allowed before and 255 characters are allowed after the @ sign. This pattern verifies only that the string contains an unquoted @ sign. See https://tools.ietf.org/html/rfc5322#section-3.4.1."},"first_name":{"type":"string","maxLength":100,"description":"First name of the recipient."},"last_name":{"type":"string","maxLength":100,"description":"Last name of the recipient."},"phone":{"type":"number","maxLength":15,"description":"Numbers only, no dash or any other separator."},"state":{"type":"string","maxLength":35,"description":"A region / state / province for the address."}},"required":["address","city","country","postal_code"]},"swishPaymentInitiationResponse":{"title":"Swish Payment Initiation Response","type":"object","properties":{"id":{"title":"Transaction ID","type":"string","description":"The ID of the transaction.","format":"uuid-flexible"},"amount":{"type":"integer","description":"Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field."},"blocked":{"type":"boolean","description":"True if the transaction has been blocked by a ruleset, false otherwise"},"created_at":{"type":"string","description":"The time at which the transaction was created.","format":"date-time"},"customer":{"type":"string","description":"The ID of a customer"},"details":{"$ref":"#/components/schemas/ecomPaymentResponse_details"},"merchant_reference":{"type":"string","description":"A reference specified by the merchant to identify the transaction.","maxLength":50},"processor":{"type":"string","description":"The name of the processor used for this transaction","default":"SWISH"},"payment_product":{"type":"string","description":"The payment product corresponding to this transaction","default":"SWISH"},"payment_product_type":{"$ref":"#/components/schemas/PaymentProductType"},"shipping_information":{"allOf":[{"$ref":"#/components/schemas/ShippingInformationDto"}]},"status":{"type":"string","description":"The outcome of the payment request.","title":"Ecommerce Transaction Status","enum":["INITIATED","AUTHORIZED","AUTHORIZATION_VOIDED","CANCELLED","CUSTOMER_ACCEPTED","REFUNDED","FAILED","PENDING","DECLINED","SETTLEMENT_CANCELLED","SETTLEMENT_REQUESTED","SETTLEMENT_SUBMITTED","SETTLEMENT_COMPLETED","SETTLEMENT_PARTIAL","SETTLEMENT_DECLINED","VOIDED","UNKNOWN"]},"status_reason":{"type":"string","description":"The outcome of the payment request.","title":"Ecommerce Transaction Status","enum":["INITIATED","AUTHORIZED","AUTHORIZATION_VOIDED","CANCELLED","CUSTOMER_ACCEPTED","REFUNDED","FAILED","PENDING","DECLINED","SETTLEMENT_CANCELLED","SETTLEMENT_REQUESTED","SETTLEMENT_SUBMITTED","SETTLEMENT_COMPLETED","SETTLEMENT_PARTIAL","SETTLEMENT_DECLINED","VOIDED","UNKNOWN"]},"created_by":{"type":"string","description":"The ID of the user who initiated the transaction. Only set when shopper_interaction = moto, mail_order or telephone_order"},"shopper_interaction":{"type":"string","description":"Determines the sales channel the shopper gives their card details through:\n\n * `ECOMMERCE` Online transactions where the cardholder is present.\n\n * `MAIL` order transactions where the shopper is in contact with the merchant via email.\n\n * `TELEPHONE` order transactions where the shopper is in contact with the merchant via telephone.","enum":["ECOMMERCE","MAIL","TELEPHONE"],"default":"ECOMMERCE"},"geo_location":{"type":"array","description":"The latitude / longitude resolved from the customer's ip address.","items":{"type":"number"}},"city":{"type":"string","description":"The city resolved from the customer's ip address."},"country_code":{"title":"Country Code","type":"string","description":"The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.
Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.
."},"payment_request_token":{"type":"string","description":"Returned when creating an m-commerce payment request. The token to use when opening the Swish app. Please find more details at [Swish documentation](https://developer.swish.nu/documentation/guides/trigger-the-swish-app)."}}},"ecomPaymentResponse_details":{"type":"object","properties":{"auto_capture":{"type":"boolean","description":"Indicates whether the transaction would be automatically captured upon authorisation."},"mid":{"type":"string","description":"Merchant ID (MID)","format":"integer"}}},"PaymentProductType":{"title":"Payment Product Type","type":"string","description":"The payment product type corresponding to this transaction. Fees applied to the transaction, is based on the payment product","enum":["Affirm","Amex","Crypto","Diners Club International","Discover","JCB","Klarna","Maestro","Mastercard","OP Online Payment","Swish","Unknown","Visa"],"default":"Unknown"},"BadRequestV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[400],"default":400},"message":{"type":"string","enum":["At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."],"default":"At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."}},"required":["message"]},"UnauthorizedV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[401],"default":401},"message":{"type":"string","enum":["Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."],"default":"Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."}},"required":["message"]},"ForbiddenV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[403],"default":403},"message":{"type":"string","enum":["Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."],"default":"Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."}},"required":["message"]},"NotFoundV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[404],"default":404},"message":{"type":"string","enum":["The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."],"default":"The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."}},"required":["message"]},"InternalErrorV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[500],"default":500},"message":{"type":"string","enum":["Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"],"default":"Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"}},"required":["message"]}}},"paths":{"/api/v2/transactions/swish":{"post":{"tags":["Ecom Payments"],"summary":"Initiate a Swish payment","description":"Initiate a Swish payment.","operationId":"swishTransaction","parameters":[{"name":"x-vfi-api-idempotencykey","required":false,"in":"header","schema":{"type":"string","description":"A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/swishPaymentInitiationRequest"}}}},"responses":{"201":{"description":"The Swish Payment Initiation Response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/swishPaymentInitiationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestV2Docs"}}}},"401":{"description":"Unauthorised Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedV2Docs"}}}},"403":{"description":"Forbidden Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenV2Docs"}}}},"404":{"description":"Not Found Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundV2Docs"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorV2Docs"}}}}}}}}} ``` ## OP Online Payment OP Online Payment requires selecting a bank before initiating the transaction. Use the banks list endpoint first. ### Get Available Banks ## Get a list of Banks supported by OP Online Payment > Get a list of Banks supported by OP Online Payment. ```json {"openapi":"3.0.0","info":{"title":"Verifone eCommerce API","version":"2.38.1"},"servers":[{"url":"https://emea.gsc.verifone.cloud/oidc","description":"EMEA Production"},{"url":"https://us.gsc.verifone.cloud/oidc","description":"Americas Production"},{"url":"https://nz.gsc.verifone.cloud/oidc","description":"New Zealand Production"},{"url":"https://cst.test-gsc.vfims.com/oidc","description":"Global Sandbox"},{"url":"https://uscst-gb.gsc.vficloud.net/oidc","description":"Americas Sandbox"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"opOnlinePaymentGetBanksResponse":{"title":"OP Online Payment list of Banks Response","type":"array","items":{"type":"object","properties":{"bank_id":{"type":"string"},"bank_name":{"type":"string"}}}},"BadRequestV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[400],"default":400},"message":{"type":"string","enum":["At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."],"default":"At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."}},"required":["message"]},"UnauthorizedV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[401],"default":401},"message":{"type":"string","enum":["Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."],"default":"Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."}},"required":["message"]},"ForbiddenV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[403],"default":403},"message":{"type":"string","enum":["Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."],"default":"Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."}},"required":["message"]},"NotFoundV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[404],"default":404},"message":{"type":"string","enum":["The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."],"default":"The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."}},"required":["message"]},"InternalErrorV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[500],"default":500},"message":{"type":"string","enum":["Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"],"default":"Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"}},"required":["message"]}}},"paths":{"/api/v2/get-op-banks":{"get":{"tags":["Ecom Payments"],"summary":"Get a list of Banks supported by OP Online Payment","description":"Get a list of Banks supported by OP Online Payment.","operationId":"getOpBanks","responses":{"201":{"description":"The OP Online Payment list of Banks Response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/opOnlinePaymentGetBanksResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestV2Docs"}}}},"401":{"description":"Unauthorised Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedV2Docs"}}}},"403":{"description":"Forbidden Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenV2Docs"}}}},"404":{"description":"Not Found Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundV2Docs"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorV2Docs"}}}}}}}}} ``` ### Initiate OP Online Payment ## Initiate a OP Online payment > Initiate a OP Online payment. ```json {"openapi":"3.0.0","info":{"title":"Verifone eCommerce API","version":"2.38.1"},"servers":[{"url":"https://emea.gsc.verifone.cloud/oidc","description":"EMEA Production"},{"url":"https://us.gsc.verifone.cloud/oidc","description":"Americas Production"},{"url":"https://nz.gsc.verifone.cloud/oidc","description":"New Zealand Production"},{"url":"https://cst.test-gsc.vfims.com/oidc","description":"Global Sandbox"},{"url":"https://uscst-gb.gsc.vficloud.net/oidc","description":"Americas Sandbox"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"opOnlinePaymentInitiationRequest":{"title":"OP Online Payment Initiation Request","required":["amount","bank_id","cancel_url","currency_code","merchant_reference","payment_provider_contract","reject_url","return_url"],"type":"object","properties":{"payment_provider_contract":{"type":"string","description":"The identifier of payment provider contract you want to process the transaction request with.","format":"uuid-flexible","title":"paymentProviderContractId"},"bank_id":{"maxLength":40,"type":"string","description":"OP bank ID for the bank to be used"},"bank_name":{"type":"string","description":"Bank name for the selected Bank"},"amount":{"type":"integer","description":"Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field."},"customer":{"title":"Customer ID","type":"string","description":"The ID of a customer.","format":"uuid-flexible"},"dynamic_descriptor":{"maxLength":50,"type":"string","description":"A short [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) to be shown on the invoice of the customer. Please refer to the integration guide for the format requirements."},"line_items":{"type":"array","description":"The array of items being purchased.","items":{"$ref":"#/components/schemas/LineItem"}},"merchant_reference":{"type":"string","description":"A reference specified by the merchant to identify the transaction.","maxLength":50},"user_agent":{"type":"string","description":"The full user agent string of the device the customer used to submit the transaction.","maxLength":256},"currency_code":{"$ref":"#/components/schemas/CurrencyCodeEnum"},"language":{"$ref":"#/components/schemas/Language"},"message_to_customer":{"maxLength":500,"type":"string","description":"this message will be shown on OP's payment list"},"return_url":{"type":"string","description":"redirect url for successful payments"},"cancel_url":{"type":"string","description":"redirect url for cancelled payments"},"reject_url":{"type":"string","description":"redirect url for rejected payments"},"payout_reference":{"maxLength":20,"minLength":4,"pattern":"^[0-9]{4,20}$","type":"string","description":"A settlement reference specified by the merchant to identify the transaction including checksum digit."}}},"LineItem":{"title":"Ecommerce basket line items","required":["name","quantity","tax_rate","total_amount","total_tax_amount"],"type":"object","properties":{"image_url":{"type":"string","description":"Image URL for the line item"},"name":{"maxLength":255,"type":"string","description":"Descriptive name of the order line item"},"quantity":{"type":"integer","description":"Quantity of the order line item"},"unit_price":{"type":"integer","description":"Unit Price is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details."},"unit_price_tax":{"type":"integer","description":"Unit Price Tax is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details."},"tax_rate":{"type":"number","description":"Item Tax (VAT) Rate.","format":"float"},"discount_amount":{"type":"integer","description":"Discount inclusive of tax. This is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details."},"total_tax_amount":{"type":"integer","description":"Total tax amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details."},"total_amount":{"type":"integer","description":"Total Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details."},"sku":{"maxLength":127,"type":"string","description":"The stock keeping unit (SKU) for the item."},"description":{"maxLength":127,"type":"string","description":"The detailed item description."},"category":{"type":"string","description":"The item category type.
The possible values are:
* DIGITAL_GOODS - Goods that are stored, delivered, and used in their electronic format. This value is not currently supported for API callers that leverage the [PayPal for Commerce Platform](https://www.paypal.com/us/webapps/mpp/commerce-platform) product.
* DIGITAL_GOODS - A tangible item that can be shipped with proof of delivery.
","enum":["DIGITAL_GOODS","PHYSICAL_GOODS"]}},"description":"The description of item(s) that was included in a transaction or purchase."},"CurrencyCodeEnum":{"title":"Currency Code","type":"string","description":"Three-letter ISO 4217 alphabetical currency code. e.g. USD. Values correspond\nto [ISO 4217](https://wikipedia.org/wiki/ISO_4217).\n\nDeprecated: `BYR` (replaced by BYN), `FRF` (replaced by EUR), `LTL` (replaced by EUR), `LVL` (replaced by EUR), `MRO` (replaced by MRU), `STD` (replaced by STN), `USS` (no replacement), `VEF` (replaced by VES), `ZMK` (replaced by ZMV) and `BTC` (Bitcoin only supported as Crypto Amount).","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRU","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STN","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UYW","UZS","VES","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"Language":{"title":"Language","maxLength":11,"minLength":2,"type":"string","description":"The BCP-47 language tag. Composed of:"},"opOnlinePaymentInitiationResponse":{"title":"OP Online Payment Payment Initiation Response","type":"object","properties":{"id":{"title":"Transaction ID","type":"string","description":"The ID of the transaction.","format":"uuid-flexible"},"payment_url":{"type":"string","description":"The payment URL can be used to redirect to transfer the money.","format":"uri"},"amount":{"type":"integer","description":"Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field."},"created_at":{"type":"string","description":"The time at which the transaction was created.","format":"date-time"},"customer":{"type":"string","description":"The ID of a customer"},"merchant_reference":{"type":"string","description":"A reference specified by the merchant to identify the transaction.","maxLength":50},"processor":{"type":"string","description":"The name of the processor used for this transaction","default":"OP_ONLINE_PAYMENT"},"payment_product":{"type":"string","description":"The payment product corresponding to this transaction","default":"OP_ONLINE_PAYMENT"},"payment_product_type":{"$ref":"#/components/schemas/PaymentProductType"},"status":{"type":"string","description":"The outcome of the payment request.","title":"Ecommerce Transaction Status","enum":["INITIATED","AUTHORIZED","AUTHORIZATION_VOIDED","CANCELLED","CUSTOMER_ACCEPTED","REFUNDED","FAILED","PENDING","DECLINED","SETTLEMENT_CANCELLED","SETTLEMENT_REQUESTED","SETTLEMENT_SUBMITTED","SETTLEMENT_COMPLETED","SETTLEMENT_PARTIAL","SETTLEMENT_DECLINED","VOIDED","UNKNOWN"]},"status_reason":{"type":"string","description":"Message provided by the 3rd party service as additional information, when the transaction does not succeed."},"geo_location":{"type":"array","description":"The latitude / longitude resolved from the customer's ip address.","items":{"type":"number"}},"city":{"type":"string","description":"The city resolved from the customer's ip address."},"country_code":{"title":"Country Code","type":"string","description":"The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.
Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.
."},"payout_reference":{"maxLength":20,"minLength":4,"pattern":"^[0-9]{4,20}$","type":"string","description":"A settlement reference specified by the merchant to identify the transaction including checksum digit."}}},"PaymentProductType":{"title":"Payment Product Type","type":"string","description":"The payment product type corresponding to this transaction. Fees applied to the transaction, is based on the payment product","enum":["Affirm","Amex","Crypto","Diners Club International","Discover","JCB","Klarna","Maestro","Mastercard","OP Online Payment","Swish","Unknown","Visa"],"default":"Unknown"},"BadRequestV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[400],"default":400},"message":{"type":"string","enum":["At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."],"default":"At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."}},"required":["message"]},"UnauthorizedV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[401],"default":401},"message":{"type":"string","enum":["Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."],"default":"Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."}},"required":["message"]},"ForbiddenV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[403],"default":403},"message":{"type":"string","enum":["Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."],"default":"Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."}},"required":["message"]},"NotFoundV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[404],"default":404},"message":{"type":"string","enum":["The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."],"default":"The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."}},"required":["message"]},"InternalErrorV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[500],"default":500},"message":{"type":"string","enum":["Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"],"default":"Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"}},"required":["message"]}}},"paths":{"/api/v2/transactions/op-online-payment":{"post":{"tags":["Ecom Payments"],"summary":"Initiate a OP Online payment","description":"Initiate a OP Online payment.","operationId":"opOnlinePaymentTransaction","parameters":[{"name":"x-vfi-api-idempotencykey","required":false,"in":"header","schema":{"type":"string","description":"A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/opOnlinePaymentInitiationRequest"}}}},"responses":{"201":{"description":"The OP Online Payment Initiation Response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/opOnlinePaymentInitiationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestV2Docs"}}}},"401":{"description":"Unauthorised Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedV2Docs"}}}},"403":{"description":"Forbidden Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenV2Docs"}}}},"404":{"description":"Not Found Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundV2Docs"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorV2Docs"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.verifone.com/api-reference/open-api-references/ecommerce/alternative-payment-methods.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.