Creating a Buy Transaction

The Prestmit Partners API allows you to create gift card purchase transactions for your users. This guide walks you through the process of creating a buy transaction, from getting the configuration to fulfilling the order.

Overview

Creating a buy transaction involves these steps:

1. Get Configuration - Check available gift cards and payment methods
2. Calculate Payment - Get the exact amount due for the purchase
3. Create Trade - Initiate the purchase transaction
4. Monitor Status - Track payment and fulfillment
5. Fetch Codes - Retrieve delivered gift card codes

Step 1: Get Configuration

First, check what gift cards are available for purchase and which payment methods are supported.

Endpoint

GET /api/partners/v1/giftcard-trade/buy/config

Example Request

curl -X GET "https://api.prestmit.io/partners/v1/giftcard-trade/buy/config" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

The response includes:

• enabled: Whether buying is currently enabled
• paymentMethods: Available payment methods (NAIRA, CEDIS, etc.)
• availableGiftCards: Catalog of purchasable gift cards with pricing and details

Step 2: Calculate Payment

Before creating a transaction, calculate the exact payment amount required.

Endpoint

POST /api/partners/v1/giftcard-trade/buy/calculate-payment

Parameters

Example Request

curl -X POST "https://prestmit.com/api/partners/v1/giftcard-trade/buy/calculate-payment" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "giftCardSKU=922" \
  -F "price=15" \
  -F "quantity=1"

Example Response

{
  "USD": 14.1,
  "NAIRA": 2820,
  "CEDIS": 282
}

Step 3: Create Transaction

Create the buy transaction using the calculated payment amounts.

Endpoint

POST /api/partners/v1/giftcard-trade/buy/create

Parameters

Example Request

curl -X POST "https://prestmit.com/api/partners/v1/giftcard-trade/buy/create" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "giftCardSKU=922" \
  -F "price=15" \
  -F "quantity=1" \
  -F "paymentMethod=NAIRA" \
  -F "uniqueIdentifier=your-internal-ref-123"

Example Response

{
  "data": {
    "reference": "98e46262-c179-4504-b09d-7fc69c24ef30",
    "giftCard": {
      "sku": 922,
      "title": "Test Gift card",
      "minPrice": 5,
      "maxPrice": 100,
      "currency": {
        "currency": "TestService",
        "symbol": "EZ",
        "code": "EZD"
      }
    },
    "price": 5,
    "quantity": "1",
    "totalTradeAmount": 5,
    "totalTradeAmountUSD": 4.7,
    "totalPaymentAmount": 940,
    "paymentMethod": "NAIRA",
    "status": "COMPLETED"
  }
}

Step 4: Fetch Gift Card Codes

Once the transaction is completed and fulfilled, retrieve the gift card codes.

Endpoint

GET /api/partners/v1/giftcard-trade/buy/fetch-codes/{reference}

Example Request

curl -X GET "https://prestmit.com/api/partners/v1/giftcard-trade/buy/fetch-codes/98e46262-c179-4504-b09d-7fc69c24ef30" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

[
  {
    "cardNumber": "BWMB31CV2CUV1ZMH",
    "pinCode": "532314213090922821",
    "claimUrl": "https://cards.prestmit.io/card/c9070196-1c21-4741-9300-10274d81862a",
    "expireDate": ""
  }
]

Transaction History

You can retrieve transaction history to track all buy transactions:

Endpoint

GET /api/partners/v1/giftcard-trade/buy/history?page=1

Error Handling

The API returns standard HTTP status codes:

• 200 - Success
• 201 - Created successfully
• 400 - Bad request (invalid parameters)
• 422 - Validation error
• 401 - Unauthorized (invalid API key)
• 500 - Internal server error

Common Error Response

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["The amount must be between 5 and 100."]
  }
}

Best Practices

1. Always calculate payment first before creating transactions
2. Store the reference returned from transaction creation for tracking
3. Use uniqueIdentifier to link transactions to your internal systems
4. Implement proper error handling for all API calls