openapi: 3.1.0
info:
  title: Hosted Payment
  version: "1"
  description: Send shoppers to Datman's hosted payment form with an encrypted
    payload; no API key in the request.
tags:
  - name: Hosted Payment
    description: Send the shopper to Datman's hosted payment form with an encrypted
      payload. No API key in the request; the payload is encrypted on your
      server with your secret key.
paths:
  /opto/card.php:
    servers:
      - url: https://sandbox-payments.datmanpay.com
        description: Sandbox
      - url: https://payments.datmanpay.com
        description: Production
    get:
      operationId: hostedPaymentPage
      summary: Open the hosted payment form (Sale)
      description: >-
        Redirect the shopper's browser to this URL to take a card payment on
        Datman's hosted payment form. Build the URL on your server: encrypt a
        `HostedPaymentPayload` (the order, the shopper and your redirect and
        webhook URLs) with your secret key, and pass it as `data` together with
        your `pub_key`. There is no API key header.


        After the payment the shopper is sent to `redirect_url` (success) or
        `cancel_url` (cancelled). Always take the final status from the [payment
        status webhook](/api-explorer/webhooks/1/webhook/paymentStatus) sent to
        `webhook_url`, not from the redirect. See the [Hosted payment
        guide](/docs/hosted-payment) for the encryption code.
      tags:
        - Hosted Payment
      x-playground: false
      x-guide: /docs/hosted-payment
      security: []
      parameters:
        - name: data
          in: query
          required: true
          description: Your `HostedPaymentPayload` as JSON, encrypted with AES-256-CBC
            using your secret key, then base64-encoded twice (see the guide).
            URL-encode it when you build the URL.
          schema:
            type: string
            contentEncoding: base64
            contentMediaType: application/json
            contentSchema:
              $ref: "#/components/schemas/HostedPaymentPayload"
          examples:
            sale:
              summary: Encrypted sale payload (dummy value)
              value: RW5jcnlwdGVkUGF5bG9hZEdvZXNIZXJl
        - name: pub_key
          in: query
          required: true
          description: Your public key, issued by Datman together with your secret key.
            Datman uses it to find the secret that decrypts `data`.
          schema:
            type: string
          examples:
            sale:
              summary: Your public key (dummy value)
              value: pk_test_example
      responses:
        "200":
          description: An HTML page that sends the shopper's browser straight on to the
            payment form. If the request can't be processed, the page shows an
            error message instead, for example "Unable to process this request!"
            (a required key is missing, or `data` doesn't decrypt with your
            secret) or "Online payment not available for this merchant
            account!".
          content:
            text/html:
              schema:
                type: string
              examples:
                redirect:
                  summary: Shopper forwarded to the payment form
                  value: <meta http-equiv='refresh' content='0;url=https://...'>
                requestError:
                  summary: Missing key or wrong secret
                  value: <html><center><h2>Unable to process this request!</h2></center></html>
                notAvailable:
                  summary: Online payments switched off for the merchant
                  value: <html><center><h2>Online payment not available for this merchant
                    account!</h2></center></html>
        "301":
          description: The browser is redirected (`Location` header) to the payment form
            instead. It follows this automatically; nothing changes for you.
          headers:
            Location:
              description: Where the browser goes next.
              schema:
                type: string
components:
  schemas:
    HostedPaymentPayload:
      title: HostedPaymentPayload
      description: The payment details you encrypt into `data`. Keys are case-sensitive.
      type: object
      required:
        - host
        - merchant_id
        - order_id
        - customer_id
        - email
        - provider
        - phone_number
        - amount
        - redirect_url
        - cancel_url
        - webhook_url
        - back_url
        - first_name
        - last_name
      properties:
        host:
          type: string
          description: Your website's host, without `http://` or `https://`.
          example: sandbox.example.com
        merchant_id:
          type: integer
          description: The Datman merchant the payment is for.
          example: 63155480
        order_id:
          type:
            - string
            - integer
          description: Your unique order identifier.
          example: "987654321"
        customer_id:
          type:
            - string
            - integer
          description: Your identifier for the shopper. Saved cards are linked to it and
            can be reused for the same shopper later.
          example: CUST98765
        email:
          type: string
          format: email
          description: The shopper's email address.
          example: john.doe@example.com
        provider:
          type: string
          description: The provider value Datman gave you.
          example: provider_value
        phone_number:
          type: string
          description: The shopper's phone number, in international format.
          example: "+447911123456"
        name:
          type: string
          description: The merchant's business name.
          example: Adam's Kitchen
        amount:
          type: string
          pattern: ^\d+(\.\d{1,2})?$
          description: The amount to charge, in major units, as a string.
          example: "150.75"
        avs_house_number:
          type: string
          description: House number, for address verification.
          example: 221B
        avs_postcode:
          type: string
          description: Postcode, for address verification.
          example: NW16XE
        merchant_reference:
          type: string
          description: Your own reference for the payment.
          example: REF123456
        redirect_url:
          type: string
          format: uri
          description: Where the shopper goes after a successful payment. Use HTTPS.
          example: https://example.com/success
        cancel_url:
          type: string
          format: uri
          description: Where the shopper goes if they cancel. Use HTTPS.
          example: https://example.com/cancel
        webhook_url:
          type: string
          format: uri
          description: Where Datman sends the payment status webhook. Use HTTPS. Treat the
            webhook, not the redirect, as the final status.
          example: https://example.com/webhook
        back_url:
          type: string
          format: uri
          description: Where the shopper goes if they choose to go back to your site.
          example: https://example.com/back
        first_name:
          type: string
          description: The shopper's first name.
          example: John
        last_name:
          type: string
          description: The shopper's last name.
          example: Doe
        flat:
          type: string
          description: Flat or apartment number.
          example: 12A
        address1:
          type: string
          description: Address line 1.
          example: 221B Baker Street
        address2:
          type: string
          description: Address line 2.
          example: London
        statement_descriptor:
          type: string
          maxLength: 22
          description: Text on the shopper's card statement. Unsupported characters are
            removed and it's cut to 22 characters.
          example: ADAMS KITCHEN
        statement_descriptor_address:
          type: string
          maxLength: 20
          description: Second statement line, such as a town. Unsupported characters are
            removed and it's cut to 20 characters.
          example: London
        split_fee:
          type: array
          description: Pay part of the amount to other Datman merchants, for example a
            delivery fee to the delivery partner.
          items:
            $ref: "#/components/schemas/HostedSplitFee"
    HostedSplitFee:
      title: HostedSplitFee
      type: object
      required:
        - partner_merchant_id
        - type_id
        - value
        - value_type
      properties:
        partner_merchant_id:
          type:
            - string
            - integer
          description: The `merchant_id` that receives this part of the payment.
          example: "63155481"
        type_id:
          type:
            - string
            - integer
          description: "Commission type: 1 Food/Goods, 2 Marketplace Fee, 3 Delivery Fee,
            4 Delivery Tip, 5 Restaurant Tip, 6 Service Charge."
          example: "3"
        value:
          type:
            - string
            - number
          description: The amount, or the percentage when `value_type` is `percentage`.
          example: "10.50"
        value_type:
          type: string
          enum:
            - amount
            - percentage
          example: amount