Credit card

Prev Next

Available in Classic and VPC

Recognize and extract key-value input information from credit cards using a specialized model engine.

Request

This section describes the request format. The method and URI are as follows:

Method URI
POST /credit-card

Request headers

For information about the headers common to all CLOVA OCR APIs, see CLOVA OCR request headers.

Request body

You can include the following data in the body of your request:

If Content-Type: application/json

You can include the following data in the body of your request if the request header's Content-Type is application/json:

Field Type Required Description
version String - Version information
  • Only use V2
requestId String Required Random API call UUID
timestamp Integer Required Random API call time (timestamp)
images Array Required images details

If Content-Type: multipart/form-data

You can include the following data in the body of your request if the request header's Content-Type is multipart/form-data:

Field Type Required Description
message Object Required Request data information
message.version String Required Version information
  • Only use V2
message.requestId String Required Random API call UUID
message.timestamp Integer Required Random API call time (timestamp)
message.images Array Required images details
file File Required OCR recognition image file

images

The following describes images.

Field Type Required Description
format String Required Image format
  • jpg | jpeg | png | pdf | tif | tiff
    • Image: jpg, jpeg, png
    • Single page: pdf, tif, tiff
  • Select and enter one of the image formats
name String Required Random image name
  • Use to identify images and check response results
data String Required Base64-encoded image data
  • Can be entered if Content-Type: application/json

Request example

The request example is as follows:

If Content-Type: application/json

The request example if the request header's Content-Type is application/json is as follows:

curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/credit-card' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
--data '{
    "version": "V2",
    "requestId": "1234",
    "timestamp": "0",
    "images": [
        {
            "format": "png",
            "data": "{Base64-encoded image data}",
            "name": "creaditcard_test2"
    }]
}'

If Content-Type: multipart/form-data

The request example if the request header's Content-Type is multipart/form-data is as follows:

curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/credit-card' \
--header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
--header 'Content-Type: multipart/form-data' \
--form 'message="{\"version\": \"V2\", \"requestId\": \"1234\", \"timestamp\": 1724832750462, \"images\": [{\"format\": \"jpg\", \"name\": \"creditcard_test\"}]}"' \
--form '{file}.png"'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field Type Required Description
version String - Version information
  • Only use V2
requestId String - Random API call UUID
timestamp Integer - API call time (timestamp)
images Array - images details

images

The following describes images.

Field Type Required Description
uid String - Credit card image UID
  • Use for API validity checks
name String - Credit card image name
  • Use to identify images and check response results
inferResult String - Credit card image recognition result
  • SUCCESS | FAILURE | ERROR
    • SUCCESS: recognition successful
    • FAILURE: recognition failure
    • ERROR: recognition processing exception
message String - Result message
validationResult Object - Validity check result information
validationResult.result String - Validity check result code
  • NO_REQUESTED | UNCHECKED | ERROR | VALID | INVALID
    • NO_REQUESTED: no validation action requested (validity check failed)
    • UNCHECKED: unable to verify validation
    • ERROR: error on validation (validity check failed)
    • VALID: validation result valid (validity check succeeded)
    • INVALID: failed to pass validation
validationResult.message String - Validity check result details message
  • This value is not always returned
convertedImageInfo Object - Converted image information
  • If format is pdf or tiff
  • Coordinate values are set relative to the called image file
convertedImageInfo.width Integer - Converted image width
convertedImageInfo.height Integer - Converted image height
convertedImageInfo.pageIndex Integer - Converted image page index
creditCard Object - Credit card details
creditCard.result Object - Credit card OCR recognition result

result

The following describes creditCard.result.

Field Type Required Description
name Object - Card owner name details
number Object - Card number details
validThru Object - Card expiration date details

Common object information

The following describes the common objects.

Field Type Required Description
text String - Recognized text
confidenceScore Float - Confidence of recognized text
  • 0 - 1
  • The higher the confidence value, the more accurate the text is
boundingPoly Object - Bounding Poly information
boudningPoly.vertices Array - Bounding Poly Vertices details
subBoundingPolys Array - subBoundiongPolys details

vertices

The following describes boundingPolyVertices.

Field Type Required Description
x Float - Bounding Poly X-axis coordinate value
y Float - Bounding Poly Y-axis coordinate value

subBoundingPolys

The following describes subBoundingPolys.

Field Type Required Description
x Float - Sub Bounding Poly X-axis coordinate value
y Float - Sub Bounding Poly Y-axis coordinate value

Response status codes

For information about the HTTP status codes common to all CLOVA OCR APIs, see Common CLOVA OCR response status codes.

Response example

The response example is as follows:

Success

The following is a sample response upon a successful call.

{
    "version": "V2",
    "requestId": "1234",
    "timestamp": 1725005676747,
    "images": [
        {
            "uid": "{uid}",
            "name": "creditcard_test",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "creditCard": {
                "result": {
                    "name": {
                        "text": "KAIY*** VENY***",
                        "confidence": 0.8576972,
                        "boundingPoly": {
                            "vertices": []
                        },
                        "subBoundingPolys": [
                            {
                                "vertices": [
                                    {
                                        "x": 192.0,
                                        "y": 609.0
                                    },
                                    {
                                        "x": 407.0,
                                        "y": 609.0
                                    },
                                    {
                                        "x": 407.0,
                                        "y": 651.0
                                    },
                                    {
                                        "x": 192.0,
                                        "y": 651.0
                                    }
                                ]
                            } 
                        ]
                    },
                    "number": {
                        "text": "512571781234****",
                        "confidence": 0.999885,
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 187.0,
                                    "y": 450.0
                                },
                                {
                                    "x": 1007.0,
                                    "y": 450.0
                                },
                                {
                                    "x": 1007.0,
                                    "y": 506.0
                                },
                                {
                                    "x": 187.0,
                                    "y": 506.0
                                }
                            ]
                        },
                        "subBoundingPolys": [
                            {
                                "vertices": [
                                    {
                                        "x": 187.0,
                                        "y": 450.0
                                    },
                                    {
                                        "x": 360.0,
                                        "y": 450.0
                                    },
                                    {
                                        "x": 360.0,
                                        "y": 506.0
                                    },
                                    {
                                        "x": 187.0,
                                        "y": 506.0
                                    }
                                ]
                            },
                        ]
                    },
                    "validThru": {
                        "text": "09/23",
                        "confidence": 0.9999175,
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 585.0,
                                    "y": 557.0
                                },
                                {
                                    "x": 735.0,
                                    "y": 557.0
                                },
                                {
                                    "x": 735.0,
                                    "y": 600.0
                                },
                                {
                                    "x": 585.0,
                                    "y": 600.0
                                }
                            ]
                        },
                        "subBoundingPolys": []
                    }
                }
            }
        }
    ]
}

Failure

The following is a sample response upon a failed call.

{
    "version": "V2",
    "requestId": "4567",
    "timestamp": 1725003278037,
    "images": [
        {
            "uid": "{uid}",
            "name": "receipt_test2",
            "inferResult": "ERROR",
            "message": "Read page:0 error.",
            "validationResult": {
                "result": "NO_REQUESTED"
            }
        }
    ]
}