Payments
- Transactions
- Buyers
- Checkout Sessions
- Payment links
- Payment options
- Payouts
- Refunds
- Sessions
- Settlement records
Instruments
- Card schemes
- Card details
- Digital wallets
- Gift cards
- Payment methods
- Payment method definitions
Vault
- Account updater
- Network tokens
- Payment service tokens
- Vault Forward
- Vault Forward endpoints
- Vault Forward authentication
Connections
- All services
- Payment services
- Digital wallets
- Anti-fraud services
- Gift-card services
Other
- Flow
- Merchant accounts
- Reports
- Report executions
- Webhook subscriptions
New transaction
Attempts to create an authorization for a payment method. In some cases it is not possible to create the authorization without redirecting the user for their authorization. In these cases the status is set to indicate buyer approval is pending and an approval URL is returned.
Duplicated gift card numbers are not supported. This includes both stored gift cards, as well as those directly provided via the request.
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"
}'
{
"type": "transaction",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"amount": 1299,
"additional_identifiers": {
"payment_service_authorization_id": "authorization-1234",
"payment_service_capture_id": null,
"payment_service_processor_id": null,
"another_id": "id-1234"
},
"auth_response_code": "00",
"authorized_amount": 1299,
"authorized_at": "2013-07-16T19:23:00.000+00:00",
"approval_expires_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",
"account_number": "1234567"
},
"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",
"seller_country": "US"
}
],
"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": {
"bin": "412345",
"card_type": "credit",
"card_issuer_name": "Bank"
},
"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,
"anti_fraud_decision": "accept",
"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",
"country": "US",
"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>"
}
},
"airline": {
"passenger_name_record": "JOHN L",
"booking_code": "X36Q9C",
"ticket_number": "123-1234-151555",
"ticket_delivery_method": "other",
"issued_at": "2013-07-16T19:23:00.000+00:00",
"issued_address": "123 Broadway, New York",
"travel_agency_code": "12345",
"travel_agency_name": "Agency name",
"travel_agency_invoice_number": "EG15555155",
"travel_agency_plan_name": "B733",
"restricted_ticket": false,
"issuing_carrier_code": "A3",
"issuing_carrier_name": "Aegean Airlines",
"issuing_iata_designator": "A3",
"issuing_icao_code": "AEE",
"reservation_system": "Amadeus",
"is_cardholder_traveling": false,
"passengers": [
{
"title": "Mr.",
"first_name": "John",
"last_name": "Lunn",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"passport_number": "7700225",
"ticket_number": "LH1236699999",
"frequent_flyer_number": "15885566",
"date_of_birth": "2013-07-16",
"age_group": "adult"
}
],
"legs": [
{
"carrier_code": "LY",
"carrier_name": "El Al Israel Airlines",
"iata_designator": "LY",
"icao_code": "ELY",
"flight_number": "BA98",
"departure_at": "2013-07-16T19:23:00.000+00:00",
"departure_country": "UK",
"departure_city": "London",
"departure_airport": "LHR",
"arrival_at": "2013-07-16T19:23:00.000+00:00",
"arrival_country": "UK",
"arrival_city": "London",
"arrival_airport": "LHR",
"fare_basis_code": "WH7LNR",
"flight_class": "E",
"stop_over": false,
"route_type": "round_trip",
"coupon_number": "15885566",
"fare_amount": 100,
"fee_amount": 100,
"tax_amount": 100,
"departure_tax_amount": 100,
"seat_class": "F"
}
]
},
"updated_at": "2013-07-16T19:23:00.000+00:00",
"voided_at": "2013-07-16T19:23:00.000+00:00",
"settled_currency": "GBP",
"settled_amount": 1000,
"settled": true,
"account_funding_transaction": true,
"recipient": {
"first_name": "John",
"last_name": "Lunn",
"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"
},
"account_number": "1234567",
"date_of_birth": "1996-08-31"
},
"merchant_advice_code": "01"
}
This endpoint requires the transactions.write
scope.
Authorizations
Bearer authentication header of the form Bearer <token>
, where <token>
is your auth token.
Headers
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.
255
"bffa9ce6-7a8a-449c-889a-65bd2ee86903"
Body
A request to create a transaction.
Response
Returns the created transaction.
A transaction record.
Was this page helpful?
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"
}'
{
"type": "transaction",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"amount": 1299,
"additional_identifiers": {
"payment_service_authorization_id": "authorization-1234",
"payment_service_capture_id": null,
"payment_service_processor_id": null,
"another_id": "id-1234"
},
"auth_response_code": "00",
"authorized_amount": 1299,
"authorized_at": "2013-07-16T19:23:00.000+00:00",
"approval_expires_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",
"account_number": "1234567"
},
"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",
"seller_country": "US"
}
],
"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": {
"bin": "412345",
"card_type": "credit",
"card_issuer_name": "Bank"
},
"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,
"anti_fraud_decision": "accept",
"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",
"country": "US",
"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>"
}
},
"airline": {
"passenger_name_record": "JOHN L",
"booking_code": "X36Q9C",
"ticket_number": "123-1234-151555",
"ticket_delivery_method": "other",
"issued_at": "2013-07-16T19:23:00.000+00:00",
"issued_address": "123 Broadway, New York",
"travel_agency_code": "12345",
"travel_agency_name": "Agency name",
"travel_agency_invoice_number": "EG15555155",
"travel_agency_plan_name": "B733",
"restricted_ticket": false,
"issuing_carrier_code": "A3",
"issuing_carrier_name": "Aegean Airlines",
"issuing_iata_designator": "A3",
"issuing_icao_code": "AEE",
"reservation_system": "Amadeus",
"is_cardholder_traveling": false,
"passengers": [
{
"title": "Mr.",
"first_name": "John",
"last_name": "Lunn",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"passport_number": "7700225",
"ticket_number": "LH1236699999",
"frequent_flyer_number": "15885566",
"date_of_birth": "2013-07-16",
"age_group": "adult"
}
],
"legs": [
{
"carrier_code": "LY",
"carrier_name": "El Al Israel Airlines",
"iata_designator": "LY",
"icao_code": "ELY",
"flight_number": "BA98",
"departure_at": "2013-07-16T19:23:00.000+00:00",
"departure_country": "UK",
"departure_city": "London",
"departure_airport": "LHR",
"arrival_at": "2013-07-16T19:23:00.000+00:00",
"arrival_country": "UK",
"arrival_city": "London",
"arrival_airport": "LHR",
"fare_basis_code": "WH7LNR",
"flight_class": "E",
"stop_over": false,
"route_type": "round_trip",
"coupon_number": "15885566",
"fare_amount": 100,
"fee_amount": 100,
"tax_amount": 100,
"departure_tax_amount": 100,
"seat_class": "F"
}
]
},
"updated_at": "2013-07-16T19:23:00.000+00:00",
"voided_at": "2013-07-16T19:23:00.000+00:00",
"settled_currency": "GBP",
"settled_amount": 1000,
"settled": true,
"account_funding_transaction": true,
"recipient": {
"first_name": "John",
"last_name": "Lunn",
"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"
},
"account_number": "1234567",
"date_of_birth": "1996-08-31"
},
"merchant_advice_code": "01"
}