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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

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-06-07",
    "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-06-07",
  "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

Responses

204

No Content

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

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-06-07",
    "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

Create the transaction

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

Authorise the payment

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

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

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

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-06-07",
  "expiresAt": "2026-06-07",
  "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

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

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-06-07",
  "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

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

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-06-07",
  "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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

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.

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:

PAYPAL * {merchant descriptor} {dynamicDescriptor}

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?

Good night

Transactions

Create Transaction

Create transaction

Update Transaction

Update transaction

Authorise Transaction

How It Works

Create the transaction

Authorise the payment

Capture when ready

Authorize transaction

Capture Transaction

Capture transaction

Refund Transaction

Refund transaction

Cancel Authorisation (Void)

Cancel authorisation

Intent Values

`CAPTURE`

`AUTHORIZE`

Dynamic Descriptor