openapi: 3.0.3
info:
title: Ravelin 3D Secure Server API
version: '1'
description: |
Ravelin's PSP-agnostic, PCI 3DS-validated 3D Secure Server API. Implements EMV 3DS 2.x
Authentication Request (AReq), Challenge, Result, and Version Lookup operations against
3ds.live.pci.ravelin.com. Supports both encrypted payment method payloads and unencrypted
PAN, dynamic exemption routing, and card-scheme-specific authentication values (CAVV, AAV,
AEVV). Integrates with the Ravelin iOS, Android, and browser SDKs for App-based (APP),
Browser-based (BRW), and 3RI (3DS Requestor Initiated) channels.
Endpoint documentation: https://developer.ravelin.com/merchant/api/endpoints/3d-secure/.
contact:
name: Ravelin Support
url: https://support.ravelin.com/
termsOfService: https://www.ravelin.com/legal/terms-of-service
license:
name: Proprietary
servers:
- url: https://3ds.live.pci.ravelin.com
description: PCI 3DS production endpoint
tags:
- name: 3D Secure
description: EMV 3DS 2.x authentication operations.
paths:
/3ds/version:
post:
tags: [3D Secure]
summary: Look Up 3DS Version for a Card
operationId: lookup3dsVersion
description: Look up the available 3DS protocol versions for a given card. Used before initiating
an Authentication Request to determine the supported 3DS Method URL and protocol version.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [timestamp]
properties:
timestamp: { type: integer, format: int64 }
pan: { type: string }
paymentMethod: { type: object, description: 'Encrypted payment method payload.' }
responses:
'200':
description: Version lookup result.
content:
application/json:
schema:
type: object
properties:
threeDSServerTransID: { type: string }
acsStartProtocolVersion: { type: string }
acsEndProtocolVersion: { type: string }
dsStartProtocolVersion: { type: string }
dsEndProtocolVersion: { type: string }
threeDSMethodURL: { type: string, format: uri }
/3ds/authenticate:
post:
tags: [3D Secure]
summary: Send a 3DS Authentication Request (AReq)
operationId: authenticate3ds
description: Send transaction, merchant, and cardholder data to the 3DS Server to initiate an
Authentication Request (AReq). Returns the transStatus and, when applicable, the data needed
to proceed to a challenge.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/AuthenticateRequest' }
responses:
'200':
description: AReq result.
content:
application/json:
schema: { $ref: '#/components/schemas/AuthenticateResponse' }
/3ds/challenge:
post:
tags: [3D Secure]
summary: Send a 3DS Challenge Request
operationId: challenge3ds
description: Submit the Challenge Request when the AReq returned transStatus=C, completing the
cardholder challenge flow (OTP, biometric, etc.).
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [timestamp, acsTransID, threeDSServerTransID]
properties:
timestamp: { type: integer, format: int64 }
acsTransID: { type: string }
threeDSServerTransID: { type: string }
responses:
'200':
description: Challenge response.
content:
application/json:
schema: { $ref: '#/components/schemas/AuthenticateResponse' }
/3ds/result:
post:
tags: [3D Secure]
summary: Retrieve a 3DS Authentication Result
operationId: result3ds
description: Retrieve the final authentication result by 3DS Server Transaction ID after a
Challenge has completed.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [timestamp, threeDSServerTransID]
properties:
timestamp: { type: integer, format: int64 }
threeDSServerTransID: { type: string }
responses:
'200':
description: Authentication result.
content:
application/json:
schema: { $ref: '#/components/schemas/AuthenticateResponse' }
components:
securitySchemes:
secretApiKey:
type: apiKey
in: header
name: Authorization
description: 'Secret API key prefixed with `token`.'
schemas:
AuthenticateRequest:
type: object
required: [timestamp, areqData]
properties:
timestamp: { type: integer, format: int64 }
pan: { type: string, description: 'Unencrypted PAN, when not using an encrypted paymentMethod.' }
paymentMethod: { type: object, description: 'Encrypted payment method payload.' }
areqData:
type: object
required: [messageCategory, deviceChannel, threeDSRequestorID, threeDSRequestorName, threeDSRequestorURL]
properties:
messageCategory:
type: string
enum: ['01', '02']
description: '01 = Payment Authentication, 02 = Non-Payment Authentication.'
deviceChannel:
type: string
enum: ['01', '02', '03']
description: '01 = APP, 02 = BRW, 03 = 3RI.'
threeDSRequestorID: { type: string }
threeDSRequestorName: { type: string }
threeDSRequestorURL: { type: string, format: uri }
purchaseAmount: { type: string }
purchaseCurrency: { type: string }
purchaseExponent: { type: string }
purchaseDate: { type: string }
acquirerMerchantID: { type: string }
acquirerBIN: { type: string }
merchantName: { type: string }
merchantCountryCode: { type: string }
mcc: { type: string }
AuthenticateResponse:
type: object
properties:
transStatus:
type: string
enum: [Y, A, N, U, C, D, R, I, S]
description: |
Authentication outcome. Y=Authenticated, A=Attempted, N=Not authenticated,
U=Authentication unavailable, C=Challenge required, D=Challenge required (decoupled),
R=Rejected, I=Informational only, S=Challenge using cardholder-facing service.
authenticationValue:
type: string
description: 'CAVV / AAV / AEVV verification value, base64 encoded.'
acsTransID: { type: string }
threeDSServerTransID: { type: string }
eci: { type: string }
liabilityShifted: { type: boolean }
acsURL: { type: string, format: uri }
cReq: { type: string, description: 'Base64 Challenge Request payload, when transStatus=C.' }
security:
- secretApiKey: []