Ctrlk
RegisterLogin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Transactions

The Transactions endpoints manage the full lifecycle of a PayPal payment — from creating an order through to authorisation, capture, refund, and void. Transactions support both immediate capture and a two-step authorise-then-capture flow.

All write operations accept an x-vfi-api-idempotencyKey header. Pass a UUID to safely retry requests without risk of processing a duplicate charge.

Create Transaction

The starting point for any PayPal payment. Creates an order with the payer and amount details and returns a transaction UUID used in all subsequent operations.

x-vfi-api-idempotencyKey is required when billingAgreementId is included in the request body.

Create transaction

post
/transactions
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Header parameters
paypalFraudIdstringOptional

PayPal Fraud Id

x-vfi-api-idempotencyKeystringOptional

A value you specify that uniquely identifies the transaction. If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about duplicating the transaction. Required when billingAgreementId is passed in the payload

Body
paymentProviderContractstringRequired

Payment Provider contract

intentstring · enumOptional

Intent of this transaction

Default: CAPTUREPossible values:
dynamicDescriptorstring · max: 22Optional

If an Order is paid using the "PayPal Wallet" the statement descriptor will appear in following format on the payer card statement: PAYPAL_prefix+(space)+merchant_descriptor+(space)+dynamicDescriptor. The PAYPAL prefix uses 8 characters. Only the first 22 characters will be displayed in the statement. For example, * The PayPal prefix toggle is PAYPAL * The merchant descriptor in the profile is Janes Gift * The soft descriptor is 800-123-1234 Then, the statement descriptor on the card is PAYPAL * Janes Gift 80.

merchantReferencestring · max: 127Optional

The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer.

descriptionstring · max: 127Optional

Purchase description

Responses
201

Created

application/json
idstringRequired

Transaction UUID from create transaction API

createdAtstring · dateRequired

Transaction creation date (ISO-8601)

statusstring · enumOptional

Transaction status

Possible values:
orderIdstringOptional

PayPal order identifier

instoreReferencestringRequired

Reference to the transaction for internal usage for instore

approvalUrlstringOptional

The URL where the customer should be redirected to approve the payment

post/transactions
POST /oidc/paypal-ecom/transactions HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 1371

{
  "paymentProviderContract": "text",
  "amount": {
    "value": 100,
    "currencyCode": "EUR"
  },
  "intent": "CAPTURE",
  "customer": {
    "email": "text",
    "payerId": "text",
    "phoneNumber": {
      "phoneType": "FAX",
      "value": "text"
    },
    "birthDate": "2026-01-01",
    "identification": {
      "taxIdentificationNumber": "text",
      "taxIdentificationType": "BR_CNPJ"
    },
    "address": {
      "country": "text",
      "postalCode": "text",
      "countrySubdivision": "text",
      "city": "text",
      "addressLine2": "text",
      "addressLine1": "text"
    },
    "firstName": "text",
    "lastName": "text"
  },
  "applicationContext": {
    "brandName": "text",
    "locale": "text",
    "landingPage": "BILLING",
    "shippingPreference": "NoShipping",
    "paymentPreference": "Any",
    "shopperAuthorization": "TEL",
    "returnUrl": "text",
    "cancelUrl": "text"
  },
  "shipping": {
    "address": {
      "country": "text",
      "postalCode": "text",
      "countrySubdivision": "text",
      "city": "text",
      "addressLine2": "text",
      "addressLine1": "text"
    },
    "fullName": "text"
  },
  "items": [
    {
      "name": "text",
      "unitAmount": {
        "currencyCode": "EUR",
        "value": 100
      },
      "tax": {
        "currencyCode": "EUR",
        "value": 100
      },
      "quantity": 1,
      "description": "text",
      "sku": "text",
      "category": "DIGITAL_GOODS"
    }
  ],
  "dynamicDescriptor": "text",
  "merchantReference": "text",
  "description": "text",
  "detailedAmount": {
    "discount": {
      "value": 100,
      "currencyCode": "EUR"
    },
    "shippingDiscount": {
      "value": 100,
      "currencyCode": "EUR"
    },
    "insurance": {
      "value": 100,
      "currencyCode": "EUR"
    },
    "handling": {
      "value": 100,
      "currencyCode": "EUR"
    },
    "shipping": {
      "value": 100,
      "currencyCode": "EUR"
    }
  }
}
{
  "id": "text",
  "createdAt": "2026-01-01",
  "status": "INITIATED",
  "orderId": "text",
  "instoreReference": "text",
  "approvalUrl": "text"
}

Update Transaction

Updates mutable fields on an existing transaction — such as intent, payer details, amount, shipping, or dynamic descriptor — prior to authorisation or capture.

Update transaction

patch
/transactions/{id}
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

Transaction UUID from create transaction API

Body
intentstring · enumOptional

Intent of this transaction

Possible values:
merchantReferencestring · max: 127Optional

The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer.

descriptionstring · max: 127Optional

Purchase description

dynamicDescriptorstring · max: 22Optional

If an Order is paid using the "PayPal Wallet" the statement descriptor will appear in following format on the payer card statement: PAYPAL_prefix+(space)+merchant_descriptor+(space)+dynamicDescriptor. The PAYPAL prefix uses 8 characters. Only the first 22 characters will be displayed in the statement. For example, * The PayPal prefix toggle is PAYPAL * The merchant descriptor in the profile is Janes Gift * The soft descriptor is 800-123-1234 Then, the statement descriptor on the card is PAYPAL * Janes Gift 80.

Responses
204

No Content

patch/transactions/{id}
PATCH /oidc/paypal-ecom/transactions/{id} HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 939

{
  "intent": "AUTHORIZE",
  "payer": {
    "email": "text",
    "payerId": "text",
    "phoneNumber": {
      "phoneType": "FAX",
      "value": "text"
    },
    "birthDate": "2026-01-01",
    "identification": {
      "taxIdentificationNumber": "text",
      "taxIdentificationType": "BR_CNPJ"
    },
    "address": {
      "country": "text",
      "postalCode": "text",
      "countrySubdivision": "text",
      "city": "text",
      "addressLine2": "text",
      "addressLine1": "text"
    },
    "firstName": "text",
    "lastName": "text"
  },
  "merchantReference": "text",
  "description": "text",
  "shipping": {
    "address": {
      "country": "text",
      "postalCode": "text",
      "countrySubdivision": "text",
      "city": "text",
      "addressLine2": "text",
      "addressLine1": "text"
    },
    "fullName": "text"
  },
  "dynamicDescriptor": "text",
  "amount": {
    "value": 100,
    "currencyCode": "EUR"
  },
  "detailedAmount": {
    "discount": {
      "value": 100,
      "currencyCode": "EUR"
    },
    "shippingDiscount": {
      "value": 100,
      "currencyCode": "EUR"
    },
    "insurance": {
      "value": 100,
      "currencyCode": "EUR"
    },
    "handling": {
      "value": 100,
      "currencyCode": "EUR"
    },
    "shipping": {
      "value": 100,
      "currencyCode": "EUR"
    }
  }
}
No content

Authorise Transaction

Authorises a previously created transaction, reserving funds on the payer's account. Use this when you want to separate authorisation from capture — for example, to verify funds before fulfilling an order.

How It Works

1

Create the transaction

Call POST /transactions to create an order and receive a transaction UUID.

2

Authorise the payment

Call POST /transactions/{id}/authorize with the transaction UUID. PayPal reserves the funds.

3

Capture when ready

Call POST /transactions/{id}/capture to complete the payment once the order is fulfilled.

Store the transaction UUID from the Create Transaction response — it is required for all subsequent authorise, capture, void, and refund calls.

Authorize transaction

post
/transactions/{id}/authorize
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

Transaction UUID from create transaction API

Header parameters
paypalFraudIdstringOptional

PayPal Fraud Id

x-vfi-api-idempotencyKeystringOptional

A value you specify that uniquely identifies the transaction. If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about duplicating the transaction.

Body
agreementIdstringOptional

PayPal billing agreement id

merchantReferencestring · max: 127Optional

The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer.

Responses
201

Created

application/json
idstringRequired

Transaction UUID from create transaction API

authorizationIdstringRequired

PayPal authorization identifier

createdAtstring · dateRequired

Authorization creation date (ISO-8601)

expiresAtstring · dateOptional

Authorization expiration date (ISO-8601)

statusstring · enumOptional

Transaction status

Possible values:
instoreReferencestringRequired

Reference to the transaction for internal usage for instore

post/transactions/{id}/authorize
POST /oidc/paypal-ecom/transactions/{id}/authorize HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 49

{
  "agreementId": "text",
  "merchantReference": "text"
}
{
  "id": "text",
  "authorizationId": "text",
  "createdAt": "2026-01-01",
  "expiresAt": "2026-01-01",
  "status": "AUTHORISED",
  "payer": {
    "payerId": "text",
    "name": {
      "firstName": "text",
      "lastName": "text"
    },
    "phoneNumber": {
      "phoneType": "FAX",
      "value": "text"
    },
    "email": "text",
    "shippingAddress": {
      "country": "text",
      "postalCode": "text",
      "countrySubdivision": "text",
      "city": "text",
      "addressLine2": "text",
      "addressLine1": "text",
      "fullName": "text"
    },
    "authorizationStatus": "text"
  },
  "instoreReference": "text"
}

Capture Transaction

Captures funds on an authorised transaction, completing the payment. Also used for direct (non-pre-auth) captures when intent is set to CAPTURE during transaction creation.

Capture transaction

post
/transactions/{id}/capture
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

Transaction UUID from create transaction API

Header parameters
paypalFraudIdstringOptional

PayPal Fraud Id

x-vfi-api-idempotencyKeystringOptional

A value you specify that uniquely identifies the transaction. If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about duplicating the transaction.

Body
descriptionstring · max: 127Optional

An informational note about the capture. Appears in both the payer's transaction history and the emails that the payer receives.

agreementIdstringOptional

Billing Agreement id

merchantReferencestring · max: 127Optional

The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer.

Responses
201

Created

application/json
idstringRequired

Transaction UUID from create transaction API

captureIdstringRequired

PayPal capture identifier

isFinalCapturebooleanOptional

Flag telling if capture is final or not

instoreReferencestringRequired

Reference to the transaction for internal usage for instore

createdAtstring · dateRequired

Capture creation date (ISO-8601)

statusstring · enumOptional

Transaction status

Possible values:
post/transactions/{id}/capture
POST /oidc/paypal-ecom/transactions/{id}/capture HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 114

{
  "amount": {
    "value": 100,
    "currencyCode": "EUR"
  },
  "description": "text",
  "agreementId": "text",
  "merchantReference": "text"
}
{
  "id": "text",
  "captureId": "text",
  "isFinalCapture": true,
  "instoreReference": "text",
  "createdAt": "2026-01-01",
  "status": "AUTHORISED",
  "payer": {
    "payerId": "text",
    "name": {
      "firstName": "text",
      "lastName": "text"
    },
    "phoneNumber": {
      "phoneType": "FAX",
      "value": "text"
    },
    "email": "text",
    "shippingAddress": {
      "country": "text",
      "postalCode": "text",
      "countrySubdivision": "text",
      "city": "text",
      "addressLine2": "text",
      "addressLine1": "text",
      "fullName": "text"
    },
    "paymentStatus": "text"
  }
}

Refund Transaction

Refunds a captured transaction, in full or in part. The response contains a refund record that can be used for reconciliation.

Use the x-vfi-api-idempotencyKey header when issuing refunds to prevent duplicate refund submissions on network retries.

Refund transaction

post
/transactions/{id}/refund
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

Transaction UUID from create transaction API

Header parameters
x-vfi-api-idempotencyKeystringOptional

A value you specify that uniquely identifies the transaction. If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about duplicating the transaction.

Body
reasonstring · max: 127Optional

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.

merchantReferencestring · max: 127Optional

The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer.

Responses
201

Created

application/json
idstringRequired

Transaction UUID from create transaction API

refundIdstringRequired

Refund identifier

createdAtstring · dateRequired

Refund creation date (ISO-8601)

statusstring · enumOptional

Transaction status

Possible values:
instoreReferencestringRequired

Reference to the transaction for internal usage for instore

post/transactions/{id}/refund
POST /oidc/paypal-ecom/transactions/{id}/refund HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 88

{
  "amount": {
    "value": 100,
    "currencyCode": "EUR"
  },
  "reason": "text",
  "merchantReference": "text"
}
{
  "id": "text",
  "refundId": "text",
  "createdAt": "2026-01-01",
  "status": "AUTHORISED",
  "instoreReference": "text"
}

Cancel Authorisation (Void)

Voids an authorised transaction that has not yet been captured, releasing the reserved funds back to the payer.

Void is only applicable to transactions in an authorised-but-not-captured state. Captured transactions must be refunded instead.

Cancel authorisation

post
/transactions/{id}/void
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

Transaction UUID from create transaction API

Responses
204

No Content

post/transactions/{id}/void
POST /oidc/paypal-ecom/transactions/{id}/void HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Intent Values

CAPTURE

Funds are captured immediately at the point of authorisation. Use this for standard checkout flows where fulfilment happens at time of purchase.

AUTHORIZE

Funds are reserved but not collected. Use this when fulfilment is delayed — for example, ship-on-demand or pre-order scenarios. Follow up with POST /transactions/{id}/capture to collect.

Dynamic Descriptor

The dynamicDescriptor field controls the soft descriptor shown on the payer's card statement. It is combined with the PayPal prefix and merchant descriptor in the following format:

The PAYPAL prefix uses 8 characters. Only the first 22 characters of the combined descriptor are displayed. Keep dynamicDescriptor to 22 characters or fewer.

Example: PAYPAL prefix = PAYPAL, merchant descriptor = Janes Gift, dynamic descriptor = 800-123-1234 → statement shows PAYPAL * Janes Gift 80

PreviousPayPal eCommerce
NextBilling Agreements

Was this helpful?