Developer tools

Reference payments

Reference payments unify multiple reference payment methods into a single end-user experience.

This method consolidates all payment methods into a single flow and allows the customer to choose a payment method from the same widget.

This integration is designed for deferred (offline) payments without the complexity of multiple technical integrations.

Requirements

To make reference payments, you need:

  • At least one active Connection with reference type.
  • An initialized Payment widget.

1. Create a payment order with reference

Create a reference payment order:

  1. Create an order via the DEUNA API.
  2. Include include_payment_options in the request order.
  3. Define the object list in include_payment_options.
    • payment_method: Sets the value to "reference" to offer the option of payment by reference.
    • processors: Defines a list of payment processors referenced for the order.

📘

For more information on the structure of the order request, refer to Create order.

Example

{
  "order": {
     // ... otros atributos de la orden (por ejemplo, `amount`, `currency`) ...
    "include_payment_options": [
      {
        "payment_method": "reference",
        "processors": [
          "baz_reference",
          "oxxo_reference",
          "safetypay_express"
        ]
      }
    ]
	// ... otros atributos de la orden ...
  }
}

2. Display the Payment widget

With the created order, display the Payment Widget in your application. Use the DeunaSDK.initPaymentWidget(...) function that is provided by the SDK.

await DeunaSDK.initPaymentWidget({
  orderToken: "YOUR_ORDER_TOKEN",
  callbacks: {...},
  ...
});

deunaSDK.initPaymentWidget(
  orderToken: "<DEUNA order token>",
  callbacks: PaymentWidgetCallbacks(
    onSuccess: { order in
      self.deunaSDK.close()
    },
    onError: { type in
      // Manejo de errores
    },
    onClosed: { action in
      // Widget cerrado
    },
  ),
)

deunaSDK.initPaymentWidget(
  orderToke = "<DEUNA order token>",
  callbacks = PaymentWidgetCallbacks().apply {
    onSucces = { order ->
      deunaSDK.close()
    },
    onError = { type ->
      // Manejo de errores
    },
    onClosed = { action ->
      // Widget cerrado
    },
  },
)

deunaSDK.initPaymentWidget({
  orderToken: "YOUR_ORDER_TOKEN",
  callbacks: {...},
  ...
});








3. View and download the payment receipt

When a user sends a payment request with reference:

  1. The user clicks Pay.
  2. The widget invokes submit to send the payment request.
  3. The order status in DEUNA changes to pending.
  4. The associated payment status updates to processing.
  5. Use the DeunaSDK.initVoucherWidget function, provided by the SDK.
  6. The function allows the user to view and download the payment receipt with reference.

📘

DeunaSDK.initVoucherWidget requires that order_token corresponds to the processing payment status.

Considerations

Keep the following considerations in mind when creating reference payments:

  • Variability of receipt information. The structure and information contained in the payment receipt may vary significantly depending on the reference processor the customer selects.

  • Handling multiple receipts. In certain scenarios, there might be more than one receipt associated with a referenced payment order. If this occurs, the payment order interface VoucherWidget must allow the user to select, view, and download the receipt they need.

  • Alternatives in case of receipt unavailability. If payment receipts are unavailable, your app should be prepared to offer alternatives to the user. This might include displaying an informative message, offering the option to retry the payment, or providing other contact and support methods to resolve the situation.

📘

If proof of payment is not displayed, then you must verify that the order and payment meet the established conditions.

await DeunaSDK.initVoucherWidget({
  orderToken: "YOUR_ORDER_TOKEN",
  callbacks: {...},
  ...
});

deunaSDK.initVoucherWidget({
  orderToken: "YOUR_ORDER_TOKEN",
  callbacks: PaymentWidgetCallbacks(...)
  ...
});

deunaSDK.initVoucherWidget(
  orderToke = "<DEUNA order token>",
  callbacks = PaymentWidgetCallbacks().apply {
  },
)

deunaSDK.initVoucherWidget({
  orderToken: "YOUR_ORDER_TOKEN",
  callbacks: {
    onDownloadFile: (file) => {
      const { type, data } = file;
      console.log("👀 onDownloadFile", type, data);
      const mapper = {
        [DownloadType.URL]: () => {
          // TODO: Implement download from url
        },
        [DownloadType.BASE64]: () => {
          // TODO: Implement download from image base64
        },
      };
      mapper[type]();
    },
  },
});