swagger: '2.0'
schemes:
  - https
host: merchants.api.crypto.xmoney.com/
basePath: api/
x-servers:
  - url: 'https://merchants.api.crypto.xmoney.com/api/'
    description: Production server (live)
  - url: 'https://merchants.api.sandbox.crypto.xmoney.com/api/'
    description: Sandbox server (test)
info:
  x-logo:
    url: api_logo.png
    backgroundColor: '#FAFAFA'
  title: xMoney API
  version: 1.1.0
  contact:
    email: integrations@xmoney.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  description: |
    The xMoney API is organized around
    [REST](https://en.wikipedia.org/wiki/Representational_state_transfer),
    particularly using the [JSON:API spec](https://jsonapi.org/). Our API has
    resource-oriented URLs, returns JSON responses and uses standard HTTP
    response codes and verbs.

    # Introduction

    The xMoney API is divided into two separate use cases.  

    The [Stores API](#tag/Store-Order) which uses an API Key as authentication and provides
    endpoints to be used by plugins or other integrations with your store.
    In addition to the API Key we provide a Webhooks Secret used to sign the webhook responses
    to the payments progress. That Webhook Secret is essential to ensure the payment progress is not 
    spoofed by a third party.

    The [Merchants API](#tag/Session) is comprised by all the endpoints we use to power our
    Merchant dashboard. They are public so that you can integrate with
    your own system as you please, but we do recommend using our dashboard as
    much as possible, as we'll be sure to keep it up to date and as useful as
    possible.

    # Authentication

    Both APIs have different methods of authentication, which are explained below:
    <!-- ReDoc-Inject: <security-definitions> -->
externalDocs:
  description: Check out the repo
  url: 'https://github.com/utrustdev/merchant-api-spec'
produces:
  - application/vnd.api+json
consumes:
  - application/vnd.api+json
tags:
  - name: Store Order
  - name: Webhooks
    description: |
      To sync with the progress of Order payment we use webhooks. To ensure that the webhooks are 
      comming from xMoney and not some unauthorized third party we create a signature for EVERY request
      the signature is included in the webhook payload and can be reconstructed for verification.
      You can use our [libraries](https://docs.crypto.xmoney.com/#section/Libraries) for this or you code it 
      yourself manually.

      ### Events

      Events are our way of letting you know when something interesting happens
      with an order. For example, when a payment for an order is confirmed, we
      create a `ORDER.PAYMENT.RECEIVED` event.

      We communicate these events via a webhooks system, which are sent to the
      URL you provide us as the `callback_url` for the order. 

      List of events:

      * `ORDER.PAYMENT.DETECTED` - Triggered when the payment is detected on the blockchain, **it doesn't happen always**, the payment can go straight to the confirmation. Bear in mind also that this event is not a payment confirmation, it still needs to be processed by xMoney
      * `ORDER.PAYMENT.RECEIVED` - Triggered when the payment is confirmed
      * `ORDER.PAYMENT.CANCELLED` - Triggered when the payment is cancelled

      #### Verifying events

      Since these events are sent from us to you, you might want to verify that
      they were not tampered with in the process. To allow for that, we sign
      every event with HMAC SHA256, using the webhook secret as the
      signing key. 

      We sort the payload for each event, so that we can guarantee it will
      always be the same. To do this on your side you should first remove the
      signature field, and then recursively order each field alphabetically by
      its name. For example:

      ```
      payload = {
        "event_type":"ORDER.PAYMENT.RECEIVED",
        "resource":{
          "reference":"1400012634",
          "amount":"10.8200",
          "currency":"EUR"
        },
        "signature":"5ef8a5994e917c14479b31f690d4d2a023dfcc6059081504e3087977b21580ab",
        "state":"completed"
      }

      ordered_payload = {
        "event_type":"ORDER.PAYMENT.RECEIVED",
        "resource":{
          "amount":"10.8200",
          "currency":"EUR",
          "reference":"1400012634"
        },
        "state":"completed"
      }
      ```

      Once it's ordered, you should join it into a string, sign it and then base16
      encode it:

      ```
      joined_payload =
      “event_typeORDER.PAYMENT.RECEIVEDresourceamount10.8200resourcecurrencyEURresourcereference1400012634statecompleted"
      signed_payload = :crypto.hmac(:sha256, secret, joined_payload)
      signature = Base.encode16(signed_payload, case: :lower) # This step might not be needed (e.g. on PHP and Ruby, the hmac function already returns a base16 value)
      ```

      You can see an example of the signature validation function in PHP [here.](https://github.com/utrustdev/utrust-php/blob/e400f219b73cced5b184f2f15eded3c8654dce3c/src/Webhook/Event.php#L75)

      #### Response and retries

      We will be expecting your response to our webhook to be:
      * If everything went well → status: **200 OK**; with no body or a valid JSON (e.g. `{ success: true }`);
      * If signature or body request is invalid → status: **400 Bad Request**;
      * If something else went wrong → status: **500 Internal Server Error**;


      If our HTTP request to your system fails, we will retry 15 times with an exponential back off. It follows the 
      Fibonacci sequence pattern, therefore, the last event will be 987 minutes after the first one (that's 16h27).
      After `ORDER.PAYMENT.RECEIVED` notification fail 15 times, we will send an email with the error messages. 
  - name: Session
  - name: Account
  - name: Order
  - name: Account MultiFactor
    description: |
      The multifactor activation has two steps:
      1. Generating and retrieving a secret with [this endpoint.](#operation/multiFactorGenerateSecret)
      2. Using the authenticator code (generated with the secret) activate it with [this endpoint.](#operation/multiFactorActivate)
  - name: Account Password
  - name: Account Settings
  - name: Refund
x-tagGroups:
  - name: Stores API
    tags:
      - Store Order
      - Webhooks
  - name: Merchants API
    tags:
      - Session
      - Account
      - Account MultiFactor
      - Account Password
      - Account Settings
      - Order
      - Refund
securityDefinitions:
  Stores_API_Authentication:
    type: apiKey
    in: header
    name: 'Authorization: Bearer <api-key>'
    description: |
      To generate the API key for the authentication of requests, head to the Merchant Dashboard 
      ([sandbox](https://merchants.sandbox.crypto.xmoney.com) or [production](https://merchants.crypto.xmoney.com)) and in the
      Organizations tab view and generate your keys.
      The generated key will have a `u_live` or `u_test` prefix in order to be distinguished between 
      our sandbox and production environments, respectively.
      You will also see the Webhooks secret which you will need to [verify the events signature](#tag/Webhooks), 
      save it for later.

      For usage of the Stores API you will need to include the API key on every request in
      an `Authorization` header with the following format `Bearer <api-key>`
  Merchants_API_Authentication:
    type: apiKey
    in: header
    name: 'Authorization: Bearer <token>'
    description: |
      For the Merchant API we use a JSON Web Tokens (JWT) authentication. We call our resource
      for generating JWT [Sessions](#tag/Session).
      The generated token can be used to Authenticate your Merchant API requests using the familiar 
      `Authorization` header with `Bearer <token>`
security:
  - Merchants_API_Authentication: []
  - Stores_API_Authentication: []
paths:
  /multi_factor_auth/tfa_activation:
    post:
      tags:
        - Account MultiFactor
      summary: Requests the activation for a user
      operationId: multiFactorActivate
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: body
          name: tfa_activation
          required: true
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - tfa_activation
                  attributes:
                    type: object
                    properties:
                      code:
                        type: string
                        example: '123456'
      responses:
        '200':
          description: Multi factor activated
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - tfa_activation
                  id:
                    allOf:
                      - $ref: '#/definitions/UUID'
                    description: The user uuid
  '/multi_factor_auth/tfa_activation/{user_id}':
    delete:
      tags:
        - Account MultiFactor
      summary: Requests the deactivation for a user
      operationId: multiFactorDeactivate
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: path
          name: user_id
          type: string
          format: UUID
          required: true
        - in: body
          name: tfa_activation
          required: true
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - tfa_activation
                  attributes:
                    type: object
                    properties:
                      code:
                        type: string
                        example: '123456'
      responses:
        '200':
          description: Multi factor activated
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - tfa_activation
                  id:
                    allOf:
                      - $ref: '#/definitions/UUID'
                    description: The user uuid
  /multi_factor_auth/tfa_confirmation:
    post:
      tags:
        - Account MultiFactor
      summary: Confirm the 2FA credential
      description: 'When the user has 2FA enabled, it should call this endpoint with the current JWT session token. Then, the token in this response should replace the previous one in the next requests.'
      operationId: multiFactorConfirmation
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: body
          name: tfa_confirmation
          required: true
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - tfa_confirmation
                  attributes:
                    type: object
                    properties:
                      code:
                        type: string
                        example: '123456'
      responses:
        '200':
          description: Token generated
          schema:
            $ref: '#/definitions/TokenAfterTFA'
  /multi_factor_auth/tfa_secret:
    post:
      tags:
        - Account MultiFactor
      summary: Requests the secret for a user
      description: 'Requests the generation of a Time-based One Time Password (secret) for the user, including a URI to be included in a QR code'
      operationId: multiFactorGenerateSecret
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: body
          name: tfa_secret
          required: true
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - tfa_secret
      responses:
        '200':
          description: Secret generated
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - tfa_secret
                  id:
                    allOf:
                      - $ref: '#/definitions/UUID'
                    description: The user uuid
                  attributes:
                    type: object
                    properties:
                      secret:
                        type: string
                        example: 407c1e588e224ce48ff4caf2e2525742
                      key_uri:
                        type: string
                        description: URI to be embedded into a QR code
                        example: otpauth%3A%2F%2Ftotp%2FUTRUST%3Abraeden1983%40lueilwitz.org%3Fissuer%3DUTRUST%26secret%3DGQYDOYZRMU2TQODFGIZDIY3FGQ4GMZRUMNQWMMTFGI2TENJXGQZA
                      recovery_code:
                        type: string
                        description: A code to be given to user so that they can later recover the account if the secret is lost
                        example: c2f7a15dc34c4c1f8818094741c6aa78
  '/multi_factor_auth/tfa_secret/{user_id}':
    post:
      tags:
        - Account MultiFactor
      summary: Regenerate all the 2FA credentials
      description: To be used when the user can't generate a 2FA code. Will disable 2FA and request re-activation.
      operationId: multiFactorRegenerateSecret
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: body
          name: tfa_secret
          required: true
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - tfa_secret
                  id:
                    allOf:
                      - $ref: '#/definitions/UUID'
                    description: The user uuid
                  attributes:
                    type: object
                    properties:
                      recovery_code:
                        type: string
                        example: c2f7a15dc34c4c1f8818094741c6aa78
      responses:
        '200':
          description: Secret generated
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - tfa_secret
                  id:
                    allOf:
                      - $ref: '#/definitions/UUID'
                    description: The user uuid
                  attributes:
                    type: object
                    properties:
                      secret:
                        type: string
                        example: 407c1e588e224ce48ff4caf2e2525742
                      key_uri:
                        type: string
                        description: URI to be embedded into a QR code
                        example: otpauth%3A%2F%2Ftotp%2FUTRUST%3Abraeden1983%40lueilwitz.org%3Fissuer%3DUTRUST%26secret%3DGQYDOYZRMU2TQODFGIZDIY3FGQ4GMZRUMNQWMMTFGI2TENJXGQZA
                      recovery_code:
                        type: string
                        description: A code to be given to user so that they can later recover the account if the secret is lost
                        example: c2f7a15dc34c4c1f8818094741c6aa78
  /orders:
    get:
      tags:
        - Order
      summary: List orders for all the merchant's stores
      operationId: listOrders
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: query
          name: cursor
          description: Specifies where to start fetching data from
          type: string
        - in: query
          name: limit
          description: The maximum number of results to return per call
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        - in: query
          name: include
          type: string
          enum:
            - payment
      responses:
        '200':
          description: List of orders for merchant
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  - $ref: '#/definitions/Order'
  '/orders/{order_id}':
    get:
      tags:
        - Order
      summary: Show order details
      operationId: showOrderDetails
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: path
          name: order_id
          type: string
          format: UUID
          required: true
        - in: query
          name: include
          type: string
          enum:
            - payments
      responses:
        '200':
          description: Order details
          schema:
            type: object
            properties:
              data:
                $ref: '#/definitions/Order'
        '404':
          description: Order not found
          schema:
            $ref: '#/definitions/Error'
  '/payments/{payment_id}/refund':
    get:
      tags:
        - Refund
      summary: 'Returns a refund for the given payment, if there is one'
      operationId: getPaymentRefund
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: path
          name: payment_id
          type: string
          format: UUID
          required: true
      responses:
        '200':
          description: Refund details
          schema:
            type: object
            properties:
              data:
                $ref: '#/definitions/Refund'
        '404':
          description: Refund not found
          schema:
            $ref: '#/definitions/Error'
    post:
      tags:
        - Refund
      summary: Creates a refund proposal
      description: 'As a merchant you can only propose refunds, it''s ultimately the buyer''s decision to either accept or reject it (within a reasonable timeframe). There can only be one refund proposed per payment.For payments older than 3 months, refund is not allowed.'
      operationId: createPaymentRefundProposal
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: body
          name: refund proposal
          description: Refund proposal to send to the buyer
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - refunds
                  attributes:
                    type: object
                    properties:
                      amount:
                        type: string
                        example: '10.90'
                      reason:
                        type: string
                        example: Shirt size did not fit
                    required:
                      - amount
      responses:
        '200':
          description: Refund details
          schema:
            type: array
            properties:
              data:
                $ref: '#/definitions/Refund'
        '401':
          description: Refund not Allowed
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Refund not found
          schema:
            $ref: '#/definitions/Error'
  /session:
    post:
      tags:
        - Session
      summary: Generate a valid token for this session
      description: |
        Use your xMoney credentials to generate a JWT that you will
        need to perform any authenticated request on the Merchants API.
      operationId: generateToken
      security: []
      parameters:
        - in: body
          name: credentials
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - session
                  attributes:
                    type: object
                    properties:
                      email:
                        type: string
                        format: email
                        example: john@example.com
                      password:
                        type: string
                    required:
                      - email
                      - password
      responses:
        '200':
          description: Token generated
          schema:
            $ref: '#/definitions/Token'
        '401':
          description: Invalid credentials
          schema:
            $ref: '#/definitions/Error'
    delete:
      tags:
        - Session
      summary: Revokes the token for the current session
      operationId: revokeToken
      security:
        - Merchants_API_Authentication: []
      responses:
        '200':
          description: Token revoked
  /settings/account:
    get:
      tags:
        - Account Settings
      summary: Fetch the current account settings
      operationId: getAccountSettings
      security:
        - Merchants_API_Authentication: []
      responses:
        '200':
          description: Account settings
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - orders_redirect
                  id:
                    allOf:
                      - $ref: '#/definitions/UUID'
                  attributes:
                    $ref: '#/definitions/AccountSettings'
    patch:
      tags:
        - Account Settings
      summary: Update the account settings
      operationId: updateAccountSettings
      parameters:
        - in: body
          name: settings
          description: The settings to be updated
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - account_settings
                  id:
                    description: The current user id
                    allOf:
                      - $ref: '#/definitions/UUID'
                  attributes:
                    type: object
                    properties:
                      first_name:
                        type: string
                      last_name:
                        type: string
                    required:
                      - first_name
                      - last_name
      responses:
        '200':
          description: Account settings
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - orders_redirect
                  id:
                    allOf:
                      - $ref: '#/definitions/UUID'
                  attributes:
                    $ref: '#/definitions/AccountSettings'
  /settings/password:
    patch:
      tags:
        - Account Password
      summary: Update the account password
      operationId: updateAccountPassword
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: body
          name: account-password
          description: The password to be updated
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - password
                  id:
                    description: The current user id
                    allOf:
                      - $ref: '#/definitions/UUID'
                  attributes:
                    type: object
                    properties:
                      password:
                        type: string
                      new_password:
                        type: string
                      tfa_token:
                        type: string
                        description: Token is required if 2FA has been activated
                        example: '123456'
                    required:
                      - password
                      - new_password
      responses:
        '200':
          description: Password updated
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - password
                  id:
                    allOf:
                      - $ref: '#/definitions/UUID'
                  attributes:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Password successfully changed.
  /sign_up:
    post:
      tags:
        - Account
      summary: Creates an account
      description: |
        Provide details in order to create a merchant account
      operationId: createAccount
      security:
        - Merchants_API_Authentication: []
      parameters:
        - in: body
          name: credentials
          description: Credentials you choose to be used on your account
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - account
                  attributes:
                    type: object
                    properties:
                      email:
                        type: string
                        format: email
                      password:
                        type: string
                      organization_name:
                        type: string
                      first_name:
                        type: string
                      last_name:
                        type: string
                    required:
                      - email
                      - password
                      - organization_name
                      - first_name
                      - last_name
      responses:
        '200':
          description: Account created
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  id:
                    $ref: '#/definitions/UUID'
                  type:
                    type: string
                    enum:
                      - merchants
                  attributes:
                    type: object
        '400':
          description: Invalid credentials
          schema:
            $ref: '#/definitions/Error'
  /stores/orders:
    post:
      tags:
        - Store Order
      summary: Create an order
      description: |
        Create a new order for payment processing. Returns a url to a page where a buyer can fulfill the payment for that order.
      operationId: createOrder
      security:
        - Stores_API_Authentication: []
      parameters:
        - in: body
          name: order
          description: The order information
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - orders
                  attributes:
                    type: object
                    properties:
                      order:
                        $ref: '#/definitions/OrderInput'
                      customer:
                        $ref: '#/definitions/Customer'
                    required:
                      - order
                      - customer
      responses:
        '201':
          description: Order created
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - orders_redirect
                  id:
                    allOf:
                      - $ref: '#/definitions/UUID'
                  attributes:
                    type: object
                    properties:
                      redirect_url:
                        type: string
                        format: URL
                        example: 'https://bill.crypto.xmoney.com/uuid'
      x-code-samples:
        - lang: JavaScript
          source: |
            // configs
              const API_ROOT = "https://merchants.api.crypto.xmoney.com/api/stores/orders" // OR "https://merchants.api.sandbox.crypto.xmoney.com/api/stores/orders" (for sandbox)
              const API_KEY = // Add your API_KEY here OR fetch it from environment variables;

              // order params
              const orderParams = {
                  data: {
                      type: "orders",
                      attributes: {
                          order: {
                              reference: "order-51367",
                              amount: {
                                  total: "10.00",
                                  currency: "EUR",
                              },
                              return_urls: {
                                  return_url: "http://example.com/success",
                              }
                          },
                          customer: {
                              email: 'customer@example.com',
                              country: 'US'
                          },
                      },
                  },
              }

              // xmoney api
              const xMoneyApi = {
                  createOrder: (params, token) =>
                      fetch(API_ROOT + "/stores/orders/", {
                          method: "POST",
                          headers: {
                              "content-type": "application/vnd.api+json",
                              authorization: "Bearer " + API_KEY,
                          },
                          body: JSON.stringify(params),
                      }).then(response => response.json()),
              }

              xMoneyApi
              .createOrder(orderParams)
              .then(response => response.data.attributes.redirect_url)
  '/stores/orders/{order_id}':
    get:
      tags:
        - Store Order
      summary: Show order details
      operationId: showOrderDetails
      security:
        - Stores_API_Authentication: []
      parameters:
        - in: path
          name: order_id
          type: string
          format: UUID
          required: true
        - in: query
          name: include
          type: string
          enum:
            - payments
      responses:
        '200':
          description: Order details
          schema:
            type: object
            properties:
              data:
                $ref: '#/definitions/Order'
        '404':
          description: Order not found
          schema:
            $ref: '#/definitions/Error'
definitions:
  AccountSettings:
    type: object
    properties:
      email:
        type: string
        format: email
        example: john@example.com
      first_name:
        type: string
        example: John
      last_name:
        type: string
        example: Doe
      tfa_active:
        type: boolean
        description: True if two factor authentication has been set up
  Amount:
    type: object
    properties:
      total:
        type: string
        format: decimal
        example: '1090.00'
        description: |
          Number format "1090.00" – no commas, only one dot
      currency:
        type: string
        example: USD
        enum:
          - AED
          - ARS
          - AUD
          - BRL
          - CAD
          - CHF
          - CLP
          - CNY
          - CZK
          - DKK
          - DOP
          - EUR
          - GBP
          - HKD
          - HUF
          - IDR
          - ILS
          - INR
          - JPY
          - KRW
          - MYR
          - MXN
          - NOK
          - NZD
          - PHP
          - PKR
          - PLN
          - RON
          - RUB
          - SEK
          - SGD
          - THB
          - TWD
          - USD
          - ZAR
      details:
        type: object
        description: |
          Additional details about the amount
        properties:
          subtotal:
            type: string
            format: decimal
            example: '39.00'
          shipping:
            type: string
            format: decimal
            example: '1.00'
          tax:
            type: string
            format: decimal
            example: '1.00'
          discount:
            type: string
            format: decimal
            example: '2.00'
    required:
      - total
      - currency
  Currency:
    type: object
    properties:
      value:
        type: string
        format: decimal
        example: '40.00'
      currency:
        type: string
        example: USD
  Customer:
    type: object
    properties:
      name:
        type: string
        example: John Doe
        description: Name (first_name + last_name) - only for get endpoint
      first_name:
        type: string
        example: ''
      last_name:
        type: string
        example: ''
      email:
        type: string
        format: email
        example: john@example.com
      billing_address:
        type: string
        description: Billing address (address1 + address2) - only for get endpoint
        example: 118 Main St
      address1:
        type: string
        description: Billing address 1
        example: ''
      address2:
        type: string
        description: Billing address 2
        example: ''
      city:
        type: string
        description: Billing city
        example: New York
      state:
        type: string
        description: Billing state
        example: New York
      postcode:
        type: string
        description: Billing postcode
        example: ''
      country:
        type: string
        description: 'Billing country. Format [ISO 3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)'
        example: US
    required:
      - email
      - country
  Error:
    type: object
    properties:
      errors:
        type: array
        items:
          type: object
          properties:
            detail:
              type: string
              description: Human readable explanation of the problem
              example: Explanation of the problem
  OrderInput:
    type: object
    properties:
      reference:
        type: string
        example: order-1977
      amount:
        allOf:
          - $ref: '#/definitions/Amount'
        example:
          total: '1090.00'
          currency: USD
          details:
            subtotal: '98.00'
            shipping: '10.00'
            tax: '3.00'
            discount: '2.00'
      return_urls:
        type: object
        properties:
          return_url:
            type: string
            description: URL to redirect the user in case of everything going well
            format: url
            example: 'http://example.com/return'
          cancel_url:
            type: string
            description: URL to redirect the user in case of the order cancelled
            format: url
            example: 'http://example.com/cancel'
          callback_url:
            type: string
            description: URL to POST notification about the Order final status (webhook)
            format: url
            example: 'http://example.com/callback'
        required:
          - return_url
      line_items:
        type: array
        deprecated: true
        items:
          $ref: '#/definitions/LineItem'
    required:
      - reference
      - amount
      - return_urls
  LineItem:
    type: object
    properties:
      sku:
        type: string
        example: tsh-6110
      name:
        type: string
        example: T-Shirt White Large
      price:
        type: string
        example: '100.00'
      currency:
        type: string
        example: USD
      quantity:
        type: integer
        minimum: 1
        example: 5
    required:
      - name
      - price
      - currency
      - quantity
  Order:
    type: object
    properties:
      id:
        allOf:
          - $ref: '#/definitions/UUID'
      type:
        type: string
        enum:
          - orders
      attributes:
        type: object
        properties:
          status:
            type: string
            enum:
              - pending
              - paid
          created_at:
            type: string
            format: date-time
            example: '2018-04-26T12:48:11.954503'
          total_amount:
            allOf:
              - $ref: '#/definitions/Currency'
          customer:
            $ref: '#/definitions/Customer'
          merchant_uuid:
            allOf:
              - $ref: '#/definitions/UUID'
          items:
            type: array
            items:
              $ref: '#/definitions/LineItem'
            deprecated: true
  PartnerFeeDetails:
    type: object
    properties:
      receiver:
        type: string
        enum:
          - xmoney
        example: xmoney
      amount:
        type: object
        properties:
          total:
            type: string
            format: decimal
            example: '0.000943775'
          currency:
            type: string
            example: ETH
  Payment:
    type: object
    properties:
      id:
        allOf:
          - $ref: '#/definitions/UUID'
      type:
        type: string
        enum:
          - payments
      attributes:
        type: object
        properties:
          state:
            type: string
            enum:
              - confirmed
              - rejected
              - expired
          source:
            type: object
            properties:
              type:
                type: string
                enum:
                  - order
              id:
                allOf:
                  - $ref: '#/definitions/UUID'
          payer:
            type: object
            properties:
              payment_method:
                type: string
                enum:
                  - xmoney
                  - blockchain
          total_amount:
            allOf:
              - $ref: '#/definitions/Currency'
          transactions:
            type: array
            items:
              $ref: '#/definitions/PaymentTransaction'
  PaymentTransaction:
    type: object
    properties:
      payee:
        type: string
        enum:
          - merchant
        example: merchant
      received_amount:
        $ref: '#/definitions/Amount'
      paid_amount:
        allOf:
          - $ref: '#/definitions/Amount'
        example:
          total: '0.094377463'
          currency: ETH
          details:
            subtotal: '0.092018026'
            handling_fee: '0.002359437'
      partner_fee_details:
        $ref: '#/definitions/PartnerFeeDetails'
      exchange_rate:
        type: string
        example: '423.83000000'
      description:
        type: string
        example: The payment transaction description.
  Refund:
    type: object
    properties:
      id:
        description: Refund id
        allOf:
          - $ref: '#/definitions/UUID'
      type:
        type: string
        enum:
          - refunds
      attributes:
        type: object
        properties:
          requested_amount:
            type: string
            description: Value that was proposed
          requested_currency:
            type: string
            description: Currency in which the refund was proposed (this will match the currency used by the store at the time of purchase)
          status:
            type: string
            enum:
              - proposed
              - accepted
              - rejected
              - complete
          reason:
            type: string
            description: Reason provided by the merchant to propose a refund
  Token:
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            enum:
              - session
          id:
            allOf:
              - $ref: '#/definitions/UUID'
          attributes:
            type: object
            properties:
              token:
                type: string
                format: JWT
                example: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJtZXJjaGFudF9jbGllbnQiLCJhdXRob3JpemVkIjp0cnVlLCJleHAiOjE1NzcxMDA2MTMsImlhdCI6MTU3NDY4MTQxMywiaXNzIjoibWVyY2hhbnRfY2xpZW50IiwianRpIjoiYTFkNmRkYWEtZjFlYi00NjBkLWFiMmEtMzM4Y2NhNzcyZjBkIiwibmJmIjoxNTc0NjgxNDEyLCJyb2xlIjoib3duZXIiLCJzdWIiOiJVc2VyOmE1NzEyNzNhLThmOTEtNDIwOC04MTBkLTcwOGZjYzEyZmJmNSIsInR5cCI6ImFjY2VzcyJ9.QjPZNPlasZfCON-o-mVKQpHOVafVe7T-GLAeDBgaRJYM_DYroYDU3g-G0_WZ0Rj8x_a4YY_lXTjLsfVEkPv5kg
              tfa_missing:
                type: boolean
                description: 'Optional, only sent if TFA enabled'
  TokenAfterTFA:
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            enum:
              - session
          id:
            allOf:
              - $ref: '#/definitions/UUID'
          attributes:
            type: object
            properties:
              token:
                type: string
                format: JWT
                example: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJtZXJjaGFudF9jbGllbnQiLCJhdXRob3JpemVkIjp0cnVlLCJleHAiOjE1NzcxMDA2MTMsImlhdCI6MTU3NDY4MTQxMywiaXNzIjoibWVyY2hhbnRfY2xpZW50IiwianRpIjoiYTFkNmRkYWEtZjFlYi00NjBkLWFiMmEtMzM4Y2NhNzcyZjBkIiwibmJmIjoxNTc0NjgxNDEyLCJyb2xlIjoib3duZXIiLCJzdWIiOiJVc2VyOmE1NzEyNzNhLThmOTEtNDIwOC04MTBkLTcwOGZjYzEyZmJmNSIsInR5cCI6ImFjY2VzcyJ9.QjPZNPlasZfCON-o-mVKQpHOVafVe7T-GLAeDBgaRJYM_DYroYDU3g-G0_WZ0Rj8x_a4YY_lXTjLsfVEkPv5kg
  UUID:
    type: string
    format: UUID
    example: c8d65cc2-0c82-429a-95ea-3f65011fc2cc
