Skip to main content

Pay with Giftcard in Checkout

A Wallet Giftcard can be used as payment option in a Checkout payment. Using a gift card reduces the order amount that the payer needs to authorize.

info
  • Giftcard is not supported for payment sessions with Walley payment options enabled
  • Giftcard is not supported for payment session where splits is specified
  • Only one gift card can be used to authorize a payment session
  • Giftcard have precedence when a transaction is partially captured or refunded
  • The refunded amount to a gift card cannot exceed what was initially captured

Create gift card​

Create a gift card of 500,- NOK.

POST https://api.dintero.com/v1/accounts/{aid}/wallets/cards
Authorization: Bearer <token>
Content-Type: application/json

{
  "card_id": "string",
  "customer_id": "string",
  "name": "string",
  "amount": 50000,
  "currency": "NOK",
  "pin": {
    "format": {
      "length": 4,
      "numbers": true
    }
  },
  "card_token": {
    "format": {
      "length": 16,
      "numbers": true
    }
  }
}
info

The card_token and pin that is included in the response when a card is created must be shared with the customer. The example shows the recommended minimum lengths.

Metadata​

Use metadata to include aditional information about the gift card

We recommend that you use the metadata property to store information about the transaction/order that sold the gift card if available

{
  "card_id": "string",
  ...
  "metadata": {
    "dintero_transaction_id": "P12345678.xxxxx"
  }
}

Security​

We recommend that a separate API Client is used when accessing the Wallets API. Access to create new gift card should be limited as the system that creates payment session does not need to have access to the Wallets service

You can create webhooks subscriptions to receive wallet_transaction events sent when new gift cards are created and used

Use gift card in POS​

A flow where the payeer does not need to authorize the payment via Checkout.

The process is:

  1. Check the balance of the gift card
  2. Pay the order partially or fully with the funds available
  3. Let payeer pay the remaining amount with card/cash in POS

Check balance​

Use the info endpoint to get available funds that can be used in a sale transaction

POST https://api.dintero.com/v1/accounts/{aid}/wallets/info
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "{card_token}"
}

Create capture (sale transaction)​

Use the card_id included in the info response

POST https://api.dintero.com/v1/accounts/{aid}/wallets/transactions
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "{card_token}",
  "card_id": "string",
  "metadata": {
    "order_id": "xk39592f"
  },
  "ref_id": "string",
  "amount": 50000,
  "currency": "NOK",
  "type": "drawdown",
  "pending": false
}
info

See related API documentation for more information about balance and transaction

Use gift card in checkout​

There are two ways a gift card can be used to authorize a payment session

  • Customer provides their gift card during checkout flow
  • Merchant provides the customer gift card when payment session is created
info

Native push to payment Wallets (Vipps/MobilePay/Swish) will be disabled when gift card is enabled as the payeer must "use" their gift card before being redirected to the Wallets app. Push will be done by sending SMS containing link to checkout.

Customer initiated​

The flow allows the payer to pay fully or partially using a gift card PIN required. When the payer loads the checkout they get the option to add a gift card before they complete the authorization

POST https://checkout.dintero.com/v1/sessions-profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": {
    "return_url": "https://example.com/accept",
    "callback_url": "https://example.com/callback?method=GET",
    "merchant_terms_url": "https://example.com/terms.html"
  },
  "order": {
    "amount": 72200,
    "currency": "NOK",
    "vat_amount": 13660,
    "items": [
      {
        "amount": 72200,
        "quantity": 2,
        "line_id": "1",
        "description": "Forsvinnignspølse",
        "vat": 20,
        "id": "10"
      }
    ],
    "merchant_reference": "string"
  },
  "configuration": {
    "active_payment_types": { "enabled": true },
    "dintero": {
      "type": "payment_type",
      "wallets": {
        "type": "payment_product_type",
        "enabled": true
      }
    }
  },
  "profile_id": "string",
  "merchant": {
    "name": "string",
    "logo_url": "http://example.com"
  }
}
info

See related documentation for more information about creating payment sessions

Merchant initiated​

This flow is intended for use case where the gift card is presented before the payment session is created, e.g. the payer is authenticated and the gift card is provided from the merchant CRM system. PIN required

When the payer loads the checkout it will display that a gift card is available to be use, the payer needs to provide PIN to "activate" it.

POST https://checkout.dintero.com/v1/sessions-profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": {
    "return_url": "https://example.com/accept",
    "callback_url": "https://example.com/callback?method=GET",
    "merchant_terms_url": "https://example.com/terms.html"
  },
  "customer": {
    "gift_cards": {
      "dintero.wallets": [
          {
            "card_id": "{wallets.card_id}"
          }
      ]
    }
  },
  "order": {
    "amount": 72200,
    "currency": "NOK",
    "vat_amount": 13660,
    "items": [
      {
        "amount": 72200,
        "quantity": 2,
        "line_id": "1",
        "description": "Forsvinnignspølse",
        "vat": 20,
        "id": "10"
      }
    ],
    "merchant_reference": "string"
  },
  "configuration": {
    "active_payment_types": { "enabled": true },
    "dintero": {
      "type": "payment_type",
      "wallets": {
        "type": "payment_product_type",
        "enabled": true
      },
      "zero": {
        "type": "payment_product_type",
        "enabled": true,
        "payability": "payable"
      }
    }
  },
  "profile_id": "string",
  "merchant": {
    "name": "string",
    "logo_url": "http://example.com"
  }
}
Last updated on by Frode Aannevik