Skip to main content

H2H Integration for Instructions

Description​

The Shop Hosted integration enables merchants to receive payment instruction parameters directly via host-to-host (H2H) communication.

Overview​

This integration is specifically designed for payment methods that utilize an instruction-based integration type (dataEntryMode = instruction), where the payment provider returns parameters (such as reference codes, account numbers, or other payment identifiers) that the customer needs to complete the payment.

Key features:

  • Receive payment instructions directly via API (no payment page required)
  • Support for instruction-based payment methods (dataEntryMode = instruction)
  • Full control over instruction display on your platform

Prerequisites​

Before using this integration, ensure your payment method configuration meets the following requirements:

  1. Instruction-Based Payment Method - The payment method must use dataEntryMode = instruction. You can check this in the response of the Retrieve Payment Methods endpoint.
  2. Webhook Configuration - Configure a webhook URL to receive payment instruction parameters and status updates. See Configuring Callbacks for details.

The Shop Hosted format (shop_hosted) only works with payment methods that use an instruction-based integration type (dataEntryMode = instruction). If the payment method does not support instruction-based integration, the shop_hosted parameter will be ignored, and the standard payment flow will be used.

How It Works​

The Shop Hosted integration flow differs from standard payment flows by delivering payment instructions directly to your system:

  1. Customer Selection: The customer selects products or services on your platform and proceeds to checkout.
  2. Create Order: Your system makes a POST request to create an order with paymentPageDesign.format set to shop_hosted.
  3. Instruction Delivery: The system sends the instruction parameters directly to your callback URL.
  4. Display Instructions: Your platform displays the payment instructions to the customer using the received parameters.
  5. Payment Completion: The customer completes the payment using the provided instructions through their banking app, payment provider, or other channels.
  6. Status Updates: The system monitors the payment status and sends updates via callbacks as the payment progresses.

Integration Steps​

To implement the Shop Hosted integration:

  1. Set the format property in the paymentPageDesign object to shop_hosted in the Create Order endpoint.
  2. Ensure your payment method configuration uses an instruction-based integration type (dataEntryMode = instruction).
  3. You can provide payer information directly in the request using the payer object. This is useful when the payment provider requires payer details to generate payment instructions.
  4. Implement a callback handler to receive the operationReference object containing payment instruction parameters.
  5. Display the instruction parameters to your customer on your platform.

Request Examples​

Basic Request (Without Payer Data)​

The following example demonstrates creating an order with the Shop Hosted format for a bank transfer payment method:

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "order": {
    "orderNumber": "h2h-test-001",
    "cost": {
      "amount": "1000.00",
      "currency": "USD"
    }
  },
  "customer": {
    "customerId": "customer_123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890"
  },
  "paymentSettings": {
    "instrumentType": "bank_transfer",
    "providerCode": "katarun",
    "acquirerCode": "katarun",
    "webhookUrl": "https://your-domain.com/webhook"
  },
  "paymentPageDesign": {
    "format": "shop_hosted"
  }
}'

Request with Payer Data​

When the payment provider requires payer information, include the payer object:

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "order": {
    "orderNumber": "h2h-test-003",
    "cost": {
      "amount": "2000.00",
      "currency": "BRL"
    }
  },
  "customer": {
    "customerId": "customer_789",
    "firstName": "Carlos",
    "lastName": "Silva",
    "email": "carlos.silva@example.com",
    "phone": "+5511987654321"
  },
  "payer": {
    "personalData": {
      "firstName": "Carlos",
      "lastName": "Silva",
      "phone": "+5511987654321",
      "email": "carlos.silva@example.com"
    },
    "documentData": {
      "documentType": "BR_CPF",
      "documentNumber": "12345678901"
    },
  },
  "paymentSettings": {
    "instrumentType": "bank_transfer",
    "providerCode": "example_provider",
    "acquirerCode": "example_acquirer",
    "webhookUrl": "https://your-domain.com/webhook"
  },
  "paymentPageDesign": {
    "format": "shop_hosted"
  }
}'

Response Example​

When the order is created successfully, the system returns the order number. Note that for Shop Hosted format, the paymentLink field will be null since no payment page is generated.

{
  "data": {
    "orderNumber": "h2h-test-001",
    "paymentLink": null
  }
}

Callback with Instruction Parameters​

The callback includes the operationReference object containing the payment instruction parameters.

The operationReference object contains the instruction parameters received from the payment provider. The structure includes:

  • type: Indicates the integration type (e.g., "instruction")
  • metadata: An array of parameter objects, each containing:
    • id: The parameter name/identifier (e.g., "reference", "entity", "account_number")
    • type: The data type of the parameter (e.g., "string", "number")
    • value: The actual value of the parameter

The operationReference field structure is preliminary and subject to change. The final structure and field naming will be provided in future updates. Use this as a reference for implementation planning.

Callback Example:

{
  "data": {
    "id": 12345,
    "shopId": 115,
    "orderNumber": "h2h-test-001",
    "orderStatus": "in_progress",
    "cost": {
      "amount": "1000.00",
      "currency": "USD"
    },
    "timeLimit": "2025-11-13T10:30:00+00:00",
    "orderCreatedAt": "2025-11-12T10:30:00+00:00",
    "orderPaidAt": null,
    "autoCapture": true,
    "payments": [
      {
        "paymentId": "67890",
        "paymentType": "payment",
        "parentPayment": null,
        "cost": {
          "amount": "1000.00",
          "currency": "USD"
        },
        "acquirer": {
          "code": "katarun"
        },
        "provider": {
          "code": "katarun"
        },
        "instrumentType": "bank_transfer",
        "paymentStatus": {
          "status": "in_progress",
          "details": null
        },
        "paymentDetails": {
          "transferType": "bank_wire",
          "purpose": "Payment for order h2h-test-001"
        },
        "providerPaymentId": "provider_ref_123456",
        "transactionId": "172636307000000001"
      }
    ],
    "operation_reference": {
      "type": "instruction",
      "metadata": [
        {
          "id": "reference",
          "type": "string",
          "value": "wei3wuef4rhi5uwe"
        },
        {
          "id": "entity",
          "type": "string",
          "value": "BANK_ACCOUNT_XYZ"
        }
      ]
    },
    "customer": {
      "customerId": "customer_123",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": null,
      "phone": "+1234567890",
      "email": "john.doe@example.com"
    },
    "statusReason": null
  }
}

Advanced Usage​

Retrieving Order Status​

You can retrieve the current order status and instruction parameters at any time using the Retrieve Order Details endpoint. The operationReference object will be included.

Request:

curl -L -X GET 'https://gateway.demo.vertexgateway.com/api/v1/order/115/h2h-test-001' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response:

{
  "data": {
    "id": 12345,
    "shopId": 115,
    "orderNumber": "h2h-test-001",
    "orderStatus": "in_progress",
    "cost": {
      "amount": "1000.00",
      "currency": "USD"
    },
    "timeLimit": "2025-11-13T10:30:00+00:00",
    "orderCreatedAt": "2025-11-12T10:30:00+00:00",
    "orderPaidAt": null,
    "autoCapture": true,
    "payments": [
      {
        "paymentId": "67890",
        "paymentType": "payment",
        "parentPayment": null,
        "cost": {
          "amount": "1000.00",
          "currency": "USD"
        },
        "acquirer": {
          "code": "katarun"
        },
        "provider": {
          "code": "katarun"
        },
        "instrumentType": "bank_transfer",
        "paymentStatus": {
          "status": "in_progress",
          "details": null
        },
        "paymentDetails": {
          "transferType": "bank_wire",
          "purpose": "Payment for order h2h-test-001"
        },
        "providerPaymentId": "provider_ref_123456",
        "transactionId": "172636307000000001"
      }
    ],
    "operation_reference": {
      "type": "instruction",
      "metadata": [
        {
          "id": "reference",
          "type": "string",
          "value": "wei3wuef4rhi5uwe"
        },
        {
          "id": "entity",
          "type": "string",
          "value": "BANK_ACCOUNT_XYZ"
        }
      ]
    },
    "customer": {
      "customerId": "customer_123",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": null,
      "phone": "+1234567890",
      "email": "john.doe@example.com"
    },
    "statusReason": null
  }
}