VTEX Configuration Flow API

openapi: 3.2.0
info:
  title: VTex Payment Provider Protocol Configuration Flow API
  description: ">ℹ️ The Payment Provider Protocol is a set of definitions to help you integrate your payment processing API into the VTEX platform, including sub-acquirers, acquirers, gateways, and custom payment services. \n\nTo achieve this, you must implement a web API (REST) following the specifications described in this documentation.\n\nTo learn more about the Payment Provider Protocol, check our [Help Center article](https://help.vtex.com/en/tutorial/payment-provider-protocol--RdsT2spdq80MMwwOeEq0m).\n\n## Endpoint requirements\n\n  * Must use a standard subdomain/domain name, not an IP address.\n  * Must be served over HTTPS on port 443 with TLS 1.2 support.\n  * Must respond in less than 5 seconds when running the tests.\n  * Must respond in less than 20 seconds when in production.\n  * Must be [PCI-DSS compliant](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance) or use [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy) to accept branded cards like Visa, Mastercard, Amex, etc.\n\n## Testing\n\nYou can perform tests on your payment provider using our [VTEX - Payment Provider Test Suite](https://apps.vtex.com/vtex-payment-provider-test-suite/p).\n\n>ℹ An extra header `X-VTEX-API-Is-TestSuite` = `true` will be sent for every test suite request, to help you easily identify it and mock any required scenarios.\n\nFor more details about testing a Payment Provider, check our [Payment Provider Homologation](https://developers.vtex.com/docs/guides/payments-integration-payment-provider-homologation) article.\n\n## Common parameters in the documentation\n\n<table>\n  <tr>\n    <td><code>{{providerApiEndpoint}}</code></td>\n    <td>Provider's endpoint for the implementation.</td>\n  </tr>\n  <tr>\n    <td><code>{{X-PROVIDER-API-AppKey}}</code></td>\n    <td>Unique identifier created by the provider and configured on the provider configuration page (Admin VTEX).</td>\n  </tr>\n  <tr>\n    <td><code>{{X-PROVIDER-API-AppToken}}</code></td>\n    <td>Unique token created by the provider and configured on the provider configuration page (Admin VTEX).</td>\n  </tr>\n</table> \n\n## Payment Provider Protocol API Index\n\n### Payment Flow\n\n- `GET` [List Payment Provider Manifest](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#get-/manifest)\n- `POST` [Create payment](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments)\n- `POST` [Cancel payment](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments/-paymentId-/cancellations)\n- `POST` [Settle payment](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments/-paymentId-/settlements)\n- `POST` [Refund payment](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments/-paymentId-/refunds)\n- `POST` [Inbound request (BETA)](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments/-paymentId-/inbound-request/-action-)\n\n### Configuration Flow\n\n- `POST` [Create authorization token](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/authorization/token)\n- `GET` [Provider authentication](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#get-/authorization/redirect)\n- `GET` [Get credentials](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#get-/authorization/credentials)"
  version: '1.0'
servers:
- url: https://{providerApiEndpoint}
  description: Payment provider endpoint URL.
  variables:
    providerApiEndpoint:
      description: Payment provider endpoint URL.
      default: '{providerApiEndpoint}'
tags:
- name: Configuration Flow
paths:
  /authorization/token:
    post:
      tags:
      - Configuration Flow
      summary: VTex Create authorization token
      description: 'Creates the authorization token that will be used for VTEX to redirect the merchant to the provider''s authentication application. For more information about the Payment Provider Protocol (PPP) merchant authentication procedure, visit [Configuration Flow](https://developers.vtex.com/docs/guides/payments-integration-implementing-a-payment-provider#configuration-flow).


        > ℹ️ This request is made from VTEX to the payment provider.


        ## Permissions


        Check with your service provider to know what permissions are needed.'
      operationId: CreateAuthorizationToken
      parameters:
      - $ref: '#/components/parameters/X-PROVIDER-API-AppKey'
      - $ref: '#/components/parameters/X-PROVIDER-API-AppToken'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      security:
      - appKey: []
        appToken: []
      - VtexIdclientAutCookie: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuthorizationTokenRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success5'
              example:
                applicationId: vtex
                token: 358a5bea-07d0-4122-888a-54ab70b5f02f
      deprecated: false
  /authorization/redirect:
    get:
      tags:
      - Configuration Flow
      summary: VTex Provider authentication
      description: "Use the application of provider for merchant's authentication.\n\nVTEX will redirect the merchant to your application using the `token` we retrieved earlier.\n\nYou're expected to have a signup/signin process on your side in order to authenticate the merchant, either as a new or as an existent user.\n\nAt this point, you can present your terms an conditions, a contract, and ask for merchant's final agreement to use your services.\n\nFinally, you need to generate an `authorizationCode` that you must concatenate to the `returnUrl` we send earlier.\n\nExample:\n\n`returnUrl` = `https://admin.mystore.example.com/provider-return?authorizationCode=`\n\n`authorizationCode` = `7940597D-A63B`\n\nRedirect the merchant to:\n\n`https://admin.mystore.example.com/provider-return?authorizationCode=7940597D-A63B` \n\n For more information about the Payment Provider Protocol (PPP) merchant authentication procedure, visit [Configuration Flow](https://developers.vtex.com/docs/guides/payments-integration-implementing-a-payment-provider#configuration-flow).\n\n> ℹ️ This request is made from VTEX to the payment provider.\n\n## Permissions\n\nCheck with your service provider to know what permissions are needed."
      operationId: ProviderAuthentication
      parameters:
      - $ref: '#/components/parameters/X-PROVIDER-API-AppKey'
      - $ref: '#/components/parameters/X-PROVIDER-API-AppToken'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/applicationId'
      - name: token
        in: query
        description: You must generate a token that will be used to identify the same context when we redirect the merchant to your application.
        required: true
        style: form
        explode: true
        schema:
          type: string
          example: '{{token}}'
      security:
      - appKey: []
        appToken: []
      - VtexIdclientAutCookie: []
      responses:
        '200':
          description: OK. This endpoint does not return any data in the response body.
      deprecated: false
  /authorization/credentials:
    get:
      tags:
      - Configuration Flow
      summary: VTex Get credentials
      description: "Retrieves the merchant credentials (applicationId, appKey and appToken) registered with the payment provider. These credentials will be saved in the VTEX system and activated when the retailer decides to enable the connector.\n\n For more information about the Payment Provider Protocol (PPP) merchant authentication procedure, visit [Configuration Flow](https://developers.vtex.com/docs/guides/payments-integration-implementing-a-payment-provider#configuration-flow).\n\n> ℹ️ This request is made from VTEX to the payment provider.\n\n## Permissions\n\nCheck with your service provider to know what permissions are needed."
      operationId: GetCredentials
      parameters:
      - $ref: '#/components/parameters/X-PROVIDER-API-AppKey'
      - $ref: '#/components/parameters/X-PROVIDER-API-AppToken'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/applicationId'
      - name: authorizationCode
        in: query
        description: Code generate by affiliation that will be used to identify the merchant authorization.
        required: true
        style: form
        explode: true
        schema:
          type: string
          example: '{{authorizationCode}}'
      security:
      - appKey: []
        appToken: []
      - VtexIdclientAutCookie: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success6'
              example:
                applicationId: vtex
                appKey: c5a5e3f1-4a77-4a00-8b53-0d1adb3e9628
                appToken: 57ea254d-f3d3-488d-88d7-129766037ed1
      deprecated: false
components:
  schemas:
    Success6:
      required:
      - applicationId
      - appKey
      - appToken
      type: object
      description: Get credentials response body information.
      properties:
        applicationId:
          type: string
          description: The same `applicationId` sent in the request.
        appKey:
          type: string
          description: The value we will send in the header `X-VTEX-API-AppKey` for the payment flow.
        appToken:
          type: string
          description: The value we will send in the header `X-VTEX-API-AppToken` for the payment flow.
    Success5:
      required:
      - applicationId
      - token
      type: object
      description: Create authorization token response body information.
      properties:
        applicationId:
          type: string
          description: The same `applicationId` sent in the request.
        token:
          type: string
          description: You must generate a token that will be used to identify the same context when we redirect the merchant to your application.
    CreateAuthorizationTokenRequest:
      required:
      - applicationId
      - returnUrl
      type: object
      description: Create authorization token request body information.
      properties:
        applicationId:
          type: string
          description: VTEX application identifier.
          example: vtex
        returnUrl:
          type: string
          description: The base URL you need to use to form the final URL when redirecting the merchant back to VTEX.
          example: https://admin.mystore.example.com/provider-return?authorizationCode=
  parameters:
    X-PROVIDER-API-AppKey:
      name: X-PROVIDER-API-AppKey
      in: header
      description: Unique identifier created by the provider and configured on the provider configuration page (Admin VTEX). To use this header as authorization, check that the `usesProviderHeadersName` field is set to `true` in the payment provider's `configuration.json`. To check the `configuration.json` file, access the route {{connector}}/paymentProvider/configuration.json.
      required: true
      style: simple
      schema:
        type: string
        example: '{{X-PROVIDER-API-AppKey}}'
    Accept:
      name: Accept
      in: header
      description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    applicationId:
      name: applicationId
      in: query
      description: VTEX application identifier.
      required: true
      style: form
      explode: true
      schema:
        type: string
        example: vtex
    X-PROVIDER-API-AppToken:
      name: X-PROVIDER-API-AppToken
      in: header
      description: Unique token created by the provider and configured on the provider configuration page (Admin VTEX). To use this header as authorization, check that the `usesProviderHeadersName` field is set to `true` in the payment provider's `configuration.json`. To check the `configuration.json` file, access the route {{connector}}/paymentProvider/configuration.json
      required: true
      style: simple
      schema:
        type: string
        example: '{{X-PROVIDER-API-AppToken}}'
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
      description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
      description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
      description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'