POST
/
transactions
curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 1299,
  "currency": "USD",
  "payment_method": {
    "method": "card",
    "number": "4111111111111111",
    "expiration_date": "11/25",
    "security_code": "123",
    "redirect_url": "https://example.com/callback"
  }
}'
{
  "type": "transaction",
  "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "amount": 1299,
  "auth_response_code": "00",
  "authorized_amount": 1299,
  "authorized_at": "2013-07-16T19:23:00.000+00:00",
  "avs_response_code": "partial_match_address",
  "buyer": {
    "type": "buyer",
    "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
    "billing_details": {
      "type": "billing-details",
      "first_name": "John",
      "last_name": "Lunn",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "London",
        "country": "GB",
        "postal_code": "789123",
        "state": "Greater London",
        "state_code": "GB-LND",
        "house_number_or_name": "10",
        "line1": "10 Oxford Street",
        "line2": "New Oxford Court",
        "organization": "Gr4vy"
      },
      "tax_id": {
        "value": "12345678931",
        "kind": "gb.vat"
      }
    },
    "display_name": "John L.",
    "external_identifier": "user-789123"
  },
  "captured_amount": 999,
  "captured_at": "2013-07-16T19:23:00.000+00:00",
  "cart_items": [
    {
      "name": "GoPro HERO9 Camcorder",
      "quantity": 1,
      "unit_amount": 37999,
      "discount_amount": 0,
      "tax_amount": 0,
      "external_identifier": "item-789123",
      "sku": "sku-789123",
      "product_url": "https://example.com/items/gopro",
      "image_url": "https://example.com/images/items/gopro.png",
      "categories": [
        "<string>"
      ],
      "product_type": "physical"
    }
  ],
  "checkout_session_id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "country": "US",
  "created_at": "2013-07-16T19:23:00.000+00:00",
  "currency": "USD",
  "cvv_response_code": "match",
  "error_code": "missing_redirect_url",
  "external_identifier": "user-789123",
  "gift_card_service": {
    "type": "gift-card-service",
    "id": "6c020bf3-179b-4f4f-858d-84e39e196e0f",
    "gift_card_service_definition_id": "qwikcilver-gift-card",
    "display_name": "Qwikcilver UK"
  },
  "gift_card_redemptions": [
    {
      "type": "gift-card-redemption",
      "id": "bc3f0d5a-3529-4d31-b2b4-848d14926bbc",
      "status": "succeeded",
      "amount": 1299,
      "refunded_amount": 1299,
      "gift_card_service_redemption_id": "xYqd43gySMtori",
      "error_code": "expired_card",
      "raw_error_code": "10001",
      "raw_error_message": "Card expired.",
      "gift_card": {
        "type": "gift-card",
        "id": "e6cdf979-87e2-4796-8ff6-9784d5aed893",
        "bin": "412345",
        "sub_bin": "554",
        "last4": "1234"
      }
    }
  ],
  "instrument_type": "network_token",
  "intent": "authorize",
  "intent_outcome": "pending",
  "is_subsequent_payment": true,
  "merchant_account_id": "default",
  "merchant_initiated": true,
  "metadata": {
    "key": "value"
  },
  "method": "card",
  "multi_tender": true,
  "payment_method": {
    "type": "payment-method",
    "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    "approval_target": "any",
    "approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
    "country": "US",
    "currency": "USD",
    "details": {
      "card_type": "credit",
      "bin": "412345"
    },
    "expiration_date": "11/25",
    "external_identifier": "user-789123",
    "label": "1111",
    "last_replaced_at": "2023-07-26T19:23:00.000+00:00",
    "method": "card",
    "payment_account_reference": "V0010014629724763377327521982",
    "scheme": "visa",
    "fingerprint": "20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"
  },
  "payment_service": {
    "type": "payment-service",
    "id": "stripe-card-faaad066-30b4-4997-a438-242b0752d7e1",
    "display_name": "Stripe (Main)",
    "method": "card",
    "payment_service_definition_id": "stripe-card"
  },
  "payment_service_transaction_id": "charge_xYqd43gySMtori",
  "payment_source": "recurring",
  "pending_review": true,
  "raw_response_code": "incorrect-zip",
  "raw_response_description": "The card's postal code is incorrect. Check the card's postal code or use a\ndifferent card.",
  "reconciliation_id": "7jZXl4gBUNl0CnaLEnfXbt",
  "refunded_amount": 100,
  "scheme_transaction_id": "123456789012345",
  "shipping_details": {
    "type": "shipping-details",
    "id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
    "buyer_id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
    "first_name": "John",
    "last_name": "Lunn",
    "email_address": "john@example.com",
    "phone_number": "+1234567890",
    "address": {
      "city": "London",
      "country": "GB",
      "postal_code": "789123",
      "state": "Greater London",
      "state_code": "GB-LND",
      "house_number_or_name": "10",
      "line1": "10 Oxford Street",
      "line2": "New Oxford Court",
      "organization": "Gr4vy"
    }
  },
  "statement_descriptor": {
    "name": "GR4VY",
    "description": "Card payment",
    "city": "London",
    "phone_number": "+1234567890",
    "url": "www.gr4vy.com"
  },
  "status": "processing",
  "three_d_secure": {
    "version": "2.1.0",
    "status": "setup_error",
    "method": "challenge",
    "error_data": {
      "description": "Invalid ThreeDSCompInd",
      "detail": "The threeDSCompInd must be 'Y' when successful",
      "code": "305",
      "component": "C"
    },
    "response_data": {
      "cavv": "3q2+78r+ur7erb7vyv66vv8=",
      "eci": "05",
      "version": "<string>",
      "directory_response": "C",
      "scheme": "visa",
      "authentication_response": "Y",
      "cavv_algorithm": "<string>",
      "xid": "<string>"
    }
  },
  "updated_at": "2013-07-16T19:23:00.000+00:00",
  "voided_at": "2013-07-16T19:23:00.000+00:00"
}
This endpoint requires the transactions.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

A unique key that identifies this request. Providing this header will make this an idempotent request. We recommend using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Maximum length: 255
Example:

"bffa9ce6-7a8a-449c-889a-65bd2ee86903"

Body

application/json

A request to create a transaction.

Response

201
application/json

Returns the created transaction.

A transaction record.