Transactions

Overview

Available Operations

list - List transactions
create - Create transaction
get - Get transaction
update - Manually update a transaction
capture - Capture transaction
void_ - Void transaction
cancel - Cancel transaction
sync - Sync transaction

list

Returns a paginated list of transactions for the merchant account, sorted by most recently updated. You can filter, sort, and search transactions using query parameters.

Example Usage

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.components.*;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.ListTransactionsRequest;
import com.gr4vy.sdk.models.operations.ListTransactionsResponse;
import java.lang.Exception;
import java.time.OffsetDateTime;
import java.util.List;

public class Application {

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

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("default")
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        ListTransactionsRequest req = ListTransactionsRequest.builder()
                .cursor("ZXhhbXBsZTE")
                .createdAtLte(OffsetDateTime.parse("2022-01-01T12:00:00+08:00"))
                .createdAtGte(OffsetDateTime.parse("2022-01-01T12:00:00+08:00"))
                .updatedAtLte(OffsetDateTime.parse("2022-01-01T12:00:00+08:00"))
                .updatedAtGte(OffsetDateTime.parse("2022-01-01T12:00:00+08:00"))
                .search("transaction-12345")
                .buyerExternalIdentifier("buyer-12345")
                .buyerId("fe26475d-ec3e-4884-9553-f7356683f7f9")
                .buyerEmailAddress("john@example.com")
                .ipAddress("8.214.133.47")
                .status(List.of(
                    TransactionStatus.AUTHORIZATION_SUCCEEDED))
                .id("7099948d-7286-47e4-aad8-b68f7eb44591")
                .paymentServiceTransactionId("tx-12345")
                .externalIdentifier("transaction-12345")
                .metadata(List.of(
                    "{\"first_key\":\"first_value\",\"second_key\":\"second_value\"}"))
                .amountEq(1299L)
                .amountLte(1299L)
                .amountGte(1299L)
                .currency(List.of(
                    "USD"))
                .country(List.of(
                    "US"))
                .paymentServiceId(List.of(
                    "fffd152a-9532-4087-9a4f-de58754210f0"))
                .paymentMethodId("ef9496d8-53a5-4aad-8ca2-00eb68334389")
                .paymentMethodLabel("1234")
                .paymentMethodScheme(List.of(
                    "[",
                    "\"",
                    "v",
                    "i",
                    "s",
                    "a",
                    "\"",
                    "]"))
                .paymentMethodCountry("[\"US\"]")
                .paymentMethodFingerprint("a50b85c200ee0795d6fd33a5c66f37a4564f554355c5b46a756aac485dd168a4")
                .method(List.of(
                    Method.CARD))
                .errorCode(List.of(
                    "insufficient_funds"))
                .hasRefunds(true)
                .pendingReview(true)
                .checkoutSessionId("4137b1cf-39ac-42a8-bad6-1c680d5dab6b")
                .reconciliationId("7jZXl4gBUNl0CnaLEnfXbt")
                .hasGiftCardRedemptions(true)
                .giftCardId("356d56e5-fe16-42ae-97ee-8d55d846ae2e")
                .giftCardLast4("7890")
                .hasSettlements(true)
                .paymentMethodBin("411111")
                .paymentSource(List.of(
                    TransactionPaymentSource.RECURRING))
                .isSubsequentPayment(true)
                .merchantInitiated(true)
                .used3ds(true)
                .buyerSearch(List.of(
                    "J",
                    "o",
                    "h",
                    "n"))
                .build();


        sdk.transactions().list()
                .callAsStream()
                .forEach((ListTransactionsResponse item) -> {
                   // handle page
                });

    }
}

Parameters

Parameter	Type	Required	Description
`request`	ListTransactionsRequest	✔️	The request object to use for the request.

Response

ListTransactionsResponse

Errors

Error Type	Status Code	Content Type
models/errors/Error400	400	application/json
models/errors/Error401	401	application/json
models/errors/Error403	403	application/json
models/errors/Error404	404	application/json
models/errors/Error405	405	application/json
models/errors/Error409	409	application/json
models/errors/HTTPValidationError	422	application/json
models/errors/Error425	425	application/json
models/errors/Error429	429	application/json
models/errors/Error500	500	application/json
models/errors/Error502	502	application/json
models/errors/Error504	504	application/json
models/errors/APIException	4XX, 5XX	/

create

Create a new transaction using a supported payment method. If additional buyer authorization is required, an approval URL will be returned. Duplicated gift card numbers are not supported.

Example Usage

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.components.TransactionCreate;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.CreateTransactionResponse;
import java.lang.Exception;

public class Application {

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

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("default")
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        CreateTransactionResponse res = sdk.transactions().create()
                .idempotencyKey("request-12345")
                .transactionCreate(TransactionCreate.builder()
                    .amount(1299L)
                    .currency("EUR")
                    .store(true)
                    .isSubsequentPayment(true)
                    .merchantInitiated(true)
                    .asyncCapture(true)
                    .accountFundingTransaction(true)
                    .build())
                .call();

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

Parameters

Parameter	Type	Required	Description	Example
`merchantAccountId`	JsonNullable<String>	➖	The ID of the merchant account to use for this request.
`idempotencyKey`	JsonNullable<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.	request-12345
`xForwardedFor`	Optional<String>	➖	The IP address to forward from the customer. Use this when calling our API from the server side to ensure the customer's address is passed to downstream services, rather than your server IP.	192.168.0.2
`transactionCreate`	TransactionCreate	✔️	N/A

Response

CreateTransactionResponse

Errors

Error Type	Status Code	Content Type
models/errors/Error400	400	application/json
models/errors/Error401	401	application/json
models/errors/Error403	403	application/json
models/errors/Error404	404	application/json
models/errors/Error405	405	application/json
models/errors/Error409	409	application/json
models/errors/HTTPValidationError	422	application/json
models/errors/Error425	425	application/json
models/errors/Error429	429	application/json
models/errors/Error500	500	application/json
models/errors/Error502	502	application/json
models/errors/Error504	504	application/json
models/errors/APIException	4XX, 5XX	/

get

Retrieve the details of a transaction by its unique identifier.

Example Usage

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.GetTransactionResponse;
import java.lang.Exception;

public class Application {

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

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("default")
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        GetTransactionResponse res = sdk.transactions().get()
                .transactionId("7099948d-7286-47e4-aad8-b68f7eb44591")
                .call();

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

Parameters

Parameter	Type	Required	Description	Example
`transactionId`	String	✔️	The ID of the transaction	7099948d-7286-47e4-aad8-b68f7eb44591
`merchantAccountId`	JsonNullable<String>	➖	The ID of the merchant account to use for this request.

Response

GetTransactionResponse

Errors

Error Type	Status Code	Content Type
models/errors/Error400	400	application/json
models/errors/Error401	401	application/json
models/errors/Error403	403	application/json
models/errors/Error404	404	application/json
models/errors/Error405	405	application/json
models/errors/Error409	409	application/json
models/errors/HTTPValidationError	422	application/json
models/errors/Error425	425	application/json
models/errors/Error429	429	application/json
models/errors/Error500	500	application/json
models/errors/Error502	502	application/json
models/errors/Error504	504	application/json
models/errors/APIException	4XX, 5XX	/

update

Manually updates a transaction.

Example Usage

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.components.TransactionUpdate;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.UpdateTransactionResponse;
import java.lang.Exception;

public class Application {

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

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("<id>")
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        UpdateTransactionResponse res = sdk.transactions().update()
                .transactionId("7099948d-7286-47e4-aad8-b68f7eb44591")
                .transactionUpdate(TransactionUpdate.builder()
                    .build())
                .call();

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

Parameters

Parameter	Type	Required	Description	Example
`transactionId`	String	✔️	The ID of the transaction	7099948d-7286-47e4-aad8-b68f7eb44591
`merchantAccountId`	JsonNullable<String>	➖	The ID of the merchant account to use for this request.
`transactionUpdate`	TransactionUpdate	✔️	N/A

Response

UpdateTransactionResponse

Errors

Error Type	Status Code	Content Type
models/errors/Error400	400	application/json
models/errors/Error401	401	application/json
models/errors/Error403	403	application/json
models/errors/Error404	404	application/json
models/errors/Error405	405	application/json
models/errors/Error409	409	application/json
models/errors/HTTPValidationError	422	application/json
models/errors/Error425	425	application/json
models/errors/Error429	429	application/json
models/errors/Error500	500	application/json
models/errors/Error502	502	application/json
models/errors/Error504	504	application/json
models/errors/APIException	4XX, 5XX	/

capture

Captures a previously authorized transaction. You can capture the full or a partial amount, as long as it does not exceed the authorized amount (unless over-capture is enabled).

Example Usage

package hello.world;

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

public class Application {

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

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("default")
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        CaptureTransactionRequest req = CaptureTransactionRequest.builder()
                .transactionId("7099948d-7286-47e4-aad8-b68f7eb44591")
                .transactionCaptureCreate(TransactionCaptureCreate.builder()
                    .build())
                .build();

        CaptureTransactionResponse res = sdk.transactions().capture()
                .request(req)
                .call();

        if (res.response200CaptureTransaction().isPresent()) {
            Response200CaptureTransaction unionValue = res.response200CaptureTransaction().get();
            Object raw = unionValue.value();
            if (raw instanceof Transaction) {
                Transaction transactionValue = (Transaction) raw;
                // Handle transaction variant
            } else if (raw instanceof TransactionCapture) {
                TransactionCapture transactionCaptureValue = (TransactionCapture) raw;
                // Handle transactionCapture variant
            } else {
                // Unknown or unsupported variant
            }
        }
    }
}

Parameters

Parameter	Type	Required	Description
`request`	CaptureTransactionRequest	✔️	The request object to use for the request.

Response

CaptureTransactionResponse

Errors

Error Type	Status Code	Content Type
models/errors/Error400	400	application/json
models/errors/Error401	401	application/json
models/errors/Error403	403	application/json
models/errors/Error404	404	application/json
models/errors/Error405	405	application/json
models/errors/Error409	409	application/json
models/errors/HTTPValidationError	422	application/json
models/errors/Error425	425	application/json
models/errors/Error429	429	application/json
models/errors/Error500	500	application/json
models/errors/Error502	502	application/json
models/errors/Error504	504	application/json
models/errors/APIException	4XX, 5XX	/

void_

Voids a previously authorized transaction. If the transaction was not yet successfully authorized, or was already captured, the void will not be processed. This operation releases the hold on the buyer's funds. Captured transactions can be refunded instead.

Example Usage

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.components.Transaction;
import com.gr4vy.sdk.models.components.TransactionVoid;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.Response200VoidTransaction;
import com.gr4vy.sdk.models.operations.VoidTransactionResponse;
import java.lang.Exception;
import java.lang.Object;

public class Application {

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

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("default")
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        VoidTransactionResponse res = sdk.transactions().void_()
                .transactionId("7099948d-7286-47e4-aad8-b68f7eb44591")
                .call();

        if (res.response200VoidTransaction().isPresent()) {
            Response200VoidTransaction unionValue = res.response200VoidTransaction().get();
            Object raw = unionValue.value();
            if (raw instanceof Transaction) {
                Transaction transactionValue = (Transaction) raw;
                // Handle transaction variant
            } else if (raw instanceof TransactionVoid) {
                TransactionVoid transactionVoidValue = (TransactionVoid) raw;
                // Handle transactionVoid variant
            } else {
                // Unknown or unsupported variant
            }
        }
    }
}

Parameters

Parameter	Type	Required	Description	Example
`transactionId`	String	✔️	The ID of the transaction	7099948d-7286-47e4-aad8-b68f7eb44591
`prefer`	List<String>	➖	The preferred resource type in the response.
`merchantAccountId`	JsonNullable<String>	➖	The ID of the merchant account to use for this request.
`idempotencyKey`	JsonNullable<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.	request-12345

Response

VoidTransactionResponse

Errors

Error Type	Status Code	Content Type
models/errors/Error400	400	application/json
models/errors/Error401	401	application/json
models/errors/Error403	403	application/json
models/errors/Error404	404	application/json
models/errors/Error405	405	application/json
models/errors/Error409	409	application/json
models/errors/HTTPValidationError	422	application/json
models/errors/Error425	425	application/json
models/errors/Error429	429	application/json
models/errors/Error500	500	application/json
models/errors/Error502	502	application/json
models/errors/Error504	504	application/json
models/errors/APIException	4XX, 5XX	/

cancel

Cancels a pending transaction. If the transaction was successfully authorized, or was already captured, the cancel will not be processed.

Example Usage

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.CancelTransactionResponse;
import java.lang.Exception;

public class Application {

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

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("<id>")
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        CancelTransactionResponse res = sdk.transactions().cancel()
                .transactionId("7099948d-7286-47e4-aad8-b68f7eb44591")
                .call();

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

Parameters

Parameter	Type	Required	Description	Example
`transactionId`	String	✔️	The ID of the transaction	7099948d-7286-47e4-aad8-b68f7eb44591
`merchantAccountId`	JsonNullable<String>	➖	The ID of the merchant account to use for this request.

Response

CancelTransactionResponse

Errors

Error Type	Status Code	Content Type
models/errors/Error400	400	application/json
models/errors/Error401	401	application/json
models/errors/Error403	403	application/json
models/errors/Error404	404	application/json
models/errors/Error405	405	application/json
models/errors/Error409	409	application/json
models/errors/HTTPValidationError	422	application/json
models/errors/Error425	425	application/json
models/errors/Error429	429	application/json
models/errors/Error500	500	application/json
models/errors/Error502	502	application/json
models/errors/Error504	504	application/json
models/errors/APIException	4XX, 5XX	/

sync

Synchronizes the status of a transaction with the underlying payment service provider. This is useful for transactions in a pending state to check if they've been completed or failed. Only available for some payment service providers.

Example Usage

package hello.world;

import com.gr4vy.sdk.Gr4vy;
import com.gr4vy.sdk.models.errors.*;
import com.gr4vy.sdk.models.operations.SyncTransactionResponse;
import java.lang.Exception;

public class Application {

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

        Gr4vy sdk = Gr4vy.builder()
                .merchantAccountId("default")
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        SyncTransactionResponse res = sdk.transactions().sync()
                .transactionId("2ee546e0-3b11-478e-afec-fdb362611e22")
                .call();

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

Parameters

Parameter	Type	Required	Description
`transactionId`	String	✔️	N/A
`merchantAccountId`	JsonNullable<String>	➖	The ID of the merchant account to use for this request.

Response

SyncTransactionResponse

Errors

Error Type	Status Code	Content Type
models/errors/Error400	400	application/json
models/errors/Error401	401	application/json
models/errors/Error403	403	application/json
models/errors/Error404	404	application/json
models/errors/Error405	405	application/json
models/errors/Error409	409	application/json
models/errors/HTTPValidationError	422	application/json
models/errors/Error425	425	application/json
models/errors/Error429	429	application/json
models/errors/Error500	500	application/json
models/errors/Error502	502	application/json
models/errors/Error504	504	application/json
models/errors/APIException	4XX, 5XX	/

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Transactions

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

get

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors

capture

Example Usage

Parameters

Response

Errors

void_

Example Usage

Parameters

Response

Errors

cancel

Example Usage

Parameters

Response

Errors

sync

Example Usage

Parameters

Response

Errors