Activate a gift card

using Gr4vy;
using Gr4vy.Models.Components;

var sdk = new Gr4vySDK(
    id: "example",
    server: SDKConfig.Server.Sandbox,
    bearerAuthSource: Auth.WithToken(privateKey),
    merchantAccountId: "default"
);

var res = await sdk.GiftCards.Activations.CreateAsync(giftCardActivationCreate: new GiftCardActivationCreate() {
    Number = "4123455541234561234",
});

// handle response

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.{id}.gr4vy.app/gift-cards/activations"

	payload := strings.NewReader("{\n  \"number\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.components.GiftCardActivationCreate;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.ActivateGiftCardResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {

        Gr4vy sdk = Gr4vy.builder()
                .id("example")
                .server(AvailableServers.SANDBOX)
                .merchantAccountId("default")
                .securitySource(new BearerSecuritySource.Builder(privateKey).build())
            .build();

        ActivateGiftCardResponse res = sdk.giftCards().activations().create()
                .giftCardActivationCreate(GiftCardActivationCreate.builder()
                    .number("4123455541234561234")
                    .build())
                .call();

        if (res.giftCard().isPresent()) {
            System.out.println(res.giftCard().get());
        }
    }
}

declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;

$sdk = Gr4vy\SDK::builder()
    ->setId('example')
    ->setServer('sandbox')
    ->setSecuritySource(Auth::withToken($privateKey))
    ->setMerchantAccountId('default')
    ->build();

$giftCardActivationCreate = new Gr4vy\GiftCardActivationCreate(
    number: '4123455541234561234',
);

$response = $sdk->giftCards->activations->create(
    giftCardActivationCreate: $giftCardActivationCreate
);

if ($response->giftCard !== null) {
    // handle response
}

from gr4vy import Gr4vy
import os


with Gr4vy(
    id="example",
    server="sandbox",
    merchant_account_id="default",
    bearer_auth=auth.with_token(open("./private_key.pem").read())
) as g_client:

    res = g_client.gift_cards.activations.create(number="4123455541234561234", store=False)

    # Handle response
    print(res)

import { Gr4vy, withToken } from "@gr4vy/sdk";
import fs from "fs";

const gr4vy = new Gr4vy({
    id: "example",
    server: "sandbox",
    merchantAccountId: "default",
    bearerAuth: withToken({
      privateKey: fs.readFileSync("private_key.pem", "utf8"),
    }),
});

async function run() {
  const result = await gr4vy.giftCards.activations.create({
    number: "4123455541234561234",
  });

  console.log(result);
}

run();

curl --request POST \
  --url https://api.sandbox.{id}.gr4vy.app/gift-cards/activations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "<string>"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "merchant_account_id": "<string>",
  "gift_card_service": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "display_name": "<string>",
    "type": "gift-card-service"
  },
  "bin": "<string>",
  "sub_bin": "<string>",
  "last4": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "usage_count": 123,
  "cit_usage_count": 123,
  "type": "gift-card",
  "expiration_date": "2013-07-16T19:23:00.000+00:00",
  "buyer": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reconciliation_id": "<string>",
    "merchant_account_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "type": "buyer",
    "display_name": "John Doe",
    "external_identifier": "buyer-12345",
    "billing_details": {
      "first_name": "John",
      "last_name": "Doe",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "San Jose",
        "country": "US",
        "postal_code": "94560",
        "state": "California",
        "state_code": "US-CA",
        "house_number_or_name": "10",
        "line1": "Stafford Appartments",
        "line2": "29th Street",
        "organization": "Gr4vy"
      },
      "tax_id": {
        "value": "<string>"
      }
    },
    "account_number": "<string>"
  },
  "last_used_at": "2013-07-16T19:23:00.000+00:00",
  "cit_last_used_at": "2013-07-16T19:23:00.000+00:00"
}

{
  "type": "error",
  "code": "bad_request",
  "status": 400,
  "message": "Generic error",
  "details": []
}

{
  "type": "error",
  "code": "unauthorized",
  "status": 401,
  "message": "No valid API authentication found",
  "details": []
}

{
  "type": "error",
  "code": "forbidden",
  "status": 403,
  "message": "Generic error",
  "details": []
}

{
  "type": "error",
  "code": "not_found",
  "status": 404,
  "message": "The resource could not be found",
  "details": []
}

{
  "type": "error",
  "code": "method_not_allowed",
  "status": 405,
  "message": "Method Not Allowed",
  "details": []
}

{
  "type": "error",
  "code": "duplicate_record",
  "status": 409,
  "message": "Generic error",
  "details": [],
  "resource_id": "cdc70639-cb9c-4222-a73f-b8ce39f7821b"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "type": "error",
  "code": "too_early",
  "status": 425,
  "message": "Generic error",
  "details": []
}

{
  "type": "error",
  "code": "too_many_requests",
  "status": 429,
  "message": "Generic error",
  "details": []
}

{
  "type": "error",
  "code": "server_error",
  "status": 500,
  "message": "Request could not be processed",
  "details": []
}

{
  "type": "error",
  "code": "bad_gateway",
  "status": 502,
  "message": "Request could not be processed",
  "details": []
}

{
  "type": "error",
  "code": "gateway_timeout",
  "status": 504,
  "message": "Request could not be processed",
  "details": []
}

POST

gift-cards

activations

using Gr4vy;
using Gr4vy.Models.Components;

var sdk = new Gr4vySDK(
    id: "example",
    server: SDKConfig.Server.Sandbox,
    bearerAuthSource: Auth.WithToken(privateKey),
    merchantAccountId: "default"
);

var res = await sdk.GiftCards.Activations.CreateAsync(giftCardActivationCreate: new GiftCardActivationCreate() {
    Number = "4123455541234561234",
});

// handle response

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.{id}.gr4vy.app/gift-cards/activations"

	payload := strings.NewReader("{\n  \"number\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.components.GiftCardActivationCreate;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.ActivateGiftCardResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {

        Gr4vy sdk = Gr4vy.builder()
                .id("example")
                .server(AvailableServers.SANDBOX)
                .merchantAccountId("default")
                .securitySource(new BearerSecuritySource.Builder(privateKey).build())
            .build();

        ActivateGiftCardResponse res = sdk.giftCards().activations().create()
                .giftCardActivationCreate(GiftCardActivationCreate.builder()
                    .number("4123455541234561234")
                    .build())
                .call();

        if (res.giftCard().isPresent()) {
            System.out.println(res.giftCard().get());
        }
    }
}

declare(strict_types=1);

require 'vendor/autoload.php';

use Gr4vy;

$sdk = Gr4vy\SDK::builder()
    ->setId('example')
    ->setServer('sandbox')
    ->setSecuritySource(Auth::withToken($privateKey))
    ->setMerchantAccountId('default')
    ->build();

$giftCardActivationCreate = new Gr4vy\GiftCardActivationCreate(
    number: '4123455541234561234',
);

$response = $sdk->giftCards->activations->create(
    giftCardActivationCreate: $giftCardActivationCreate
);

if ($response->giftCard !== null) {
    // handle response
}

from gr4vy import Gr4vy
import os


with Gr4vy(
    id="example",
    server="sandbox",
    merchant_account_id="default",
    bearer_auth=auth.with_token(open("./private_key.pem").read())
) as g_client:

    res = g_client.gift_cards.activations.create(number="4123455541234561234", store=False)

    # Handle response
    print(res)

import { Gr4vy, withToken } from "@gr4vy/sdk";
import fs from "fs";

const gr4vy = new Gr4vy({
    id: "example",
    server: "sandbox",
    merchantAccountId: "default",
    bearerAuth: withToken({
      privateKey: fs.readFileSync("private_key.pem", "utf8"),
    }),
});

async function run() {
  const result = await gr4vy.giftCards.activations.create({
    number: "4123455541234561234",
  });

  console.log(result);
}

run();

curl --request POST \
  --url https://api.sandbox.{id}.gr4vy.app/gift-cards/activations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "<string>"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "merchant_account_id": "<string>",
  "gift_card_service": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "display_name": "<string>",
    "type": "gift-card-service"
  },
  "bin": "<string>",
  "sub_bin": "<string>",
  "last4": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "usage_count": 123,
  "cit_usage_count": 123,
  "type": "gift-card",
  "expiration_date": "2013-07-16T19:23:00.000+00:00",
  "buyer": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reconciliation_id": "<string>",
    "merchant_account_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "type": "buyer",
    "display_name": "John Doe",
    "external_identifier": "buyer-12345",
    "billing_details": {
      "first_name": "John",
      "last_name": "Doe",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "San Jose",
        "country": "US",
        "postal_code": "94560",
        "state": "California",
        "state_code": "US-CA",
        "house_number_or_name": "10",
        "line1": "Stafford Appartments",
        "line2": "29th Street",
        "organization": "Gr4vy"
      },
      "tax_id": {
        "value": "<string>"
      }
    },
    "account_number": "<string>"
  },
  "last_used_at": "2013-07-16T19:23:00.000+00:00",
  "cit_last_used_at": "2013-07-16T19:23:00.000+00:00"
}

{
  "type": "error",
  "code": "bad_request",
  "status": 400,
  "message": "Generic error",
  "details": []
}

{
  "type": "error",
  "code": "unauthorized",
  "status": 401,
  "message": "No valid API authentication found",
  "details": []
}

{
  "type": "error",
  "code": "forbidden",
  "status": 403,
  "message": "Generic error",
  "details": []
}

{
  "type": "error",
  "code": "not_found",
  "status": 404,
  "message": "The resource could not be found",
  "details": []
}

{
  "type": "error",
  "code": "method_not_allowed",
  "status": 405,
  "message": "Method Not Allowed",
  "details": []
}

{
  "type": "error",
  "code": "duplicate_record",
  "status": 409,
  "message": "Generic error",
  "details": [],
  "resource_id": "cdc70639-cb9c-4222-a73f-b8ce39f7821b"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "type": "error",
  "code": "too_early",
  "status": 425,
  "message": "Generic error",
  "details": []
}

{
  "type": "error",
  "code": "too_many_requests",
  "status": 429,
  "message": "Generic error",
  "details": []
}

{
  "type": "error",
  "code": "server_error",
  "status": 500,
  "message": "Request could not be processed",
  "details": []
}

{
  "type": "error",
  "code": "bad_gateway",
  "status": 502,
  "message": "Request could not be processed",
  "details": []
}

{
  "type": "error",
  "code": "gateway_timeout",
  "status": 504,
  "message": "Request could not be processed",
  "details": []
}

This endpoint requires the gift-cards.write scope.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

idempotency-key

string | null

A unique key that identifies this request. If supported by the gift card service, the value will be forwarded to make the activation idempotent. We recommend using V4 UUIDs, or another random string with enough entropy to avoid collisions.

x-gr4vy-merchant-account-id

string | null

The ID of the merchant account to use for this request.

Example:

"default"

Body

application/json

The details used to activate a physical gift card.

number

string

required

The 16-19 digit number for the gift card.

Required string length: 16 - 19

Pattern: ^\d+$

Example:

"4123455541234561234"

string | null

The PIN for this gift card.

Minimum string length: 1

Example:

"1234"

amount

integer | null

The amount to load onto the gift card, in the smallest denomination for the currency. Required if currency is provided.

Required range: 0 <= x <= 99999999

Example:

5000

currency

string | null

The ISO-4217 currency code for the amount. Required if amount is provided.

Pattern: ^[A-Z]{3}$

Example:

"USD"

external_identifier

string | null

An optional external identifier for this activation.

Required string length: 1 - 200

Example:

"order-12345"

store

boolean

default:false

Whether to store the activated gift card in the vault. When true, a pin is required.

Example:

false

buyer_id

string<uuid> | null

The ID of the buyer to associate this gift card to. Only allowed when store is true. If this field is provided then the buyer_external_identifier field needs to be unset.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

buyer_external_identifier

string | null

The external_identifier of the buyer to associate this gift card to. Only allowed when store is true. If this field is provided then the buyer_id field needs to be unset.

Required string length: 1 - 200

Example:

"user-789123"

Response

Successful Response

string<uuid>

required

The ID for the gift card.

Example:

"356d56e5-fe16-42ae-97ee-8d55d846ae2e"

merchant_account_id

string

required

The ID of the merchant account this buyer belongs to.

Example:

"default"

gift_card_service

GiftCardService · object

required

The service this gift card belongs to.

Show child attributes

bin

string

required

The first 6 digits of the full gift card number.

Example:

"412345"

sub_bin

string

required

The 3 digits after the bin of the full gift card number.

Example:

"554"

last4

string

required

The last 4 digits for the gift card.

Example:

"1234"

created_at

string<date-time>

required

The date this gift card record was created at.

Example:

"2013-07-16T19:23:00.000+00:00"

updated_at

string<date-time>

required

The date this gift card record was last updated at.

Example:

"2013-07-16T19:23:00.000+00:00"

usage_count

integer

required

The number of times this gift card has been used in transactions.

Example:

100

cit_usage_count

integer

required

The number of times this gift card has been used in transactions for client initiated transactions.

Example:

50

type

string

default:gift-card

Always gift-card.

Allowed value: "gift-card"

Example:

"gift-card"

expiration_date

string<date-time> | null

The date and time when this gift card expires. This is a full date/time and may be more accurate than the actual expiry date received by the gift card service.

Example:

"2013-07-16T19:23:00.000+00:00"

buyer

Buyer · object | null

The buyer for which this gift card is stored.

Show child attributes

last_used_at

string<date-time> | null

The timestamp when this gift card was last used in a transaction.

Example:

"2013-07-16T19:23:00.000+00:00"

cit_last_used_at

string<date-time> | null

The timestamp when this gift card was last used in a transaction for client initiated transactions.

Example:

"2013-07-16T19:23:00.000+00:00"

Issue a gift card

List payment methods for a buyer

⌘I

Introduction

Transactions

Buyers

Checkout Sessions

Payment links

Payment options

Payouts

Refunds

Sessions

Settlement records

Disputes

Instruments

Vault

PSPs & Gateways

Errors

Other

Activate a gift card

Authorizations

Headers

Body

Response